Skill registry

The Skill registry turns a proven workflow into a reusable, versioned capability an agent release can pin. It is the knowledge counterpart to the quality & release plane: where a release freezes an agent's runtime configuration, a skill freezes a behavior — the trigger, context, tools, and gated policy/eval coverage that made a workflow work — into an immutable, content-addressed snapshot.

Core concepts

• Skill — a stable, per-workspace identity (a key like playbook-<id>, a name, and a description) with a mutable head pointer to its current version. The identity is durable; the head moves as new versions are cut.
• SkillVersion — an immutable, content-addressed executable snapshot. Its identity is sha256(canonicalJson(executableSnapshot)). Lifecycle status, gating evidence, the signature, and every timestamp live in their own columns and are excluded from the hash, so promoting, retiring, attaching evidence, or signing a version never changes its content identity.
• Status — a version is a CANDIDATE, promoted to ELIGIBLE once its gates pass, or RETIRED when superseded or withdrawn.

Two versions with identical executable content share a content hash and are the same version by construction ([skillId, contentHash] is unique).

Immutability

Editing skill content never mutates an existing version. A new version is cut instead, and the head advances — the same discipline the release plane applies to AgentRelease. This is what lets a release or a gate that pinned a specific version always resolve the exact executable content it was evaluated against.

Cutting is content-addressed:

• An unchanged snapshot replays to the existing version — no duplicate row, no head move (created: false).
• Edited content allocates the next monotonic ordinal (version = last + 1), writes a new immutable row, and moves the head.

Converting a playbook into a skill

A promoted playbook already carries a verified executable definition: its trigger and context, the tools it uses, the content-hashed policy revisions it was pinned against, and the eval-gated configuration digest that promoted it. Convert to skill freezes exactly that verified definition into a SkillVersion (origin = playbook) and pins the result onto Playbook.skillVersionId in one transaction, so the reference always resolves to a version that was actually written.

Because only the frozen, verified fields are folded in, the content hash is stable: re-converting an unchanged playbook is a no-op that returns the same version.

Only a promoted (enabled) playbook can be converted — an ungated draft has no verified definition worth freezing.

Release-cut pin verification

An agent release may name specific skill versions in its skillVersionIds. Each named version must exist, belong to the release's workspace, and not be RETIRED. A release cut that names a retired or unknown version is refused with the offending id named — an unknown id is an INVALID_INPUT, a retired id a CONFLICT — so a release can never be cut against a withdrawn or non-existent skill. The verified pins are folded into the release's skillRefs and thus into its configuration digest: a different pin set is a different release.

MCP tools

The registry is exposed on the agent platform:

The create_agent_release tool accepts the optional skillVersionIds pin list described above.