Skip to content

Skill Registry

Target Architecture — Final-State Design

The Skill Registry is the system of record for what agents can do. It owns the SkillDefinition and SkillVersion aggregates and records every SkillExecution. Skills are versioned, contract-bound capabilities that are reused across agents, clusters, projects, and tenants — the unit of reusability in the autonomous workforce.

A skill is a discrete capability with an explicit input/output contract — for example ConnectSoft.Skill.DesignServiceBlueprint, ConnectSoft.Skill.GenerateDomainModel, or ConnectSoft.Skill.GenerateMicroservice. Agents bind to skills; the same skill can be bound by many agent versions. The registry is implemented by ConnectSoft.Factory.AgentMesh.SkillRegistryService and seeded from ConnectSoft.AI.SoftwareFactory.Platform/registry.

Domain Model

flowchart TB
    SDef["SkillDefinition<br/>(aggregate root)"] -->|"has many"| SVer["SkillVersion<br/>(entity)"]
    SVer --> InC["InputContract<br/>(value object)"]
    SVer --> OutC["OutputContract<br/>(value object)"]
    SVer --> ToolReq["ToolRequirement[]<br/>(value object)"]
    SExec["SkillExecution<br/>(aggregate root)"] -->|"runs"| SVer
Hold "Alt" / "Option" to enable pan & zoom

SkillDefinition

The stable identity of a capability (e.g. ConnectSoft.Skill.GenerateMicroservice): name, category, owning cluster affinity, and description of intent. It has many versions and one identity.

SkillVersion

An immutable, semver-tagged contract for the skill: the input schema, output schema, required tools and permissions, model expectations (capability class, token budget guidance), and validation rules applied to its output. Versioning lets skills evolve without breaking the agents that bind them.

SkillExecution

A record of one run of a skill version within an AgentExecution: inputs consumed, context package used, model and tool invocations triggered, outputs produced, and the resulting ValidationResult. It is the traceability anchor that links a produced artifact to the exact capability that created it.

Skill Contracts

Every skill version declares a strict contract so agents are interchangeable and outputs are validatable.

{
  "skillId": "ConnectSoft.Skill.DesignServiceBlueprint",
  "version": "2.1.0",
  "input": {
    "intent": "string",
    "blueprintId": "string",
    "inputArtifacts": ["artifactRef"]
  },
  "output": {
    "outputArtifacts": ["artifactRef"],
    "summary": "string"
  },
  "tools": ["template:scaffold", "knowledge:search"],
  "model": { "capability": "reasoning", "tokenBudgetHint": 16000 },
  "validation": ["schema", "naming", "dependency", "policy"]
}

The runtime validates inputs against the contract before execution and validates outputs after, via the AgentValidationService. Contracts reference the cross-cutting metadata schema so every execution carries tenantId, traceId, agentId, and skillId.

Registration

New skills (and new versions) are onboarded through POST /skills/register, which validates the contract, naming, and tool requirements before publishing.

sequenceDiagram
    participant Client as Registrar
    participant Reg as SkillRegistryService
    participant Gov as Governance & Compliance
    Client->>Reg: POST /skills/register (definition + version)
    Reg->>Reg: validate contract + naming + tool requirements
    Reg->>Gov: authorize tool requirements
    Gov-->>Reg: approved
    Reg-->>Client: skillId + version (Registered)
    Reg->>Reg: emit SkillRegistered
Hold "Alt" / "Option" to enable pan & zoom

A successful registration emits SkillRegistered.

Versioning and Reuse

  • Skill versions are immutable and semver-tagged; the registry tracks a current version per tenant.
  • Agent versions bind to a skill version range, so a skill can be improved without forcing every agent to upgrade in lockstep.
  • A skill is reusable across clusters: e.g. a validation skill is bound by both Engineering and QA agents.
  • Reuse and outcomes are observable — the Observability & Feedback Platform attributes artifact quality back to the skill version, driving continuous improvement.

Persistence

Aggregate Store Notes
SkillDefinition Azure SQL / PostgreSQL (NHibernate) Tenant-scoped; indexed by skillId.
SkillVersion Azure SQL / PostgreSQL (NHibernate) Immutable; indexed by skillId + version.
SkillExecution Azure SQL / PostgreSQL (NHibernate) Indexed by executionId, traceId; large payloads in Blob.