Skill Governance

Operations of the Skill Registry API. Paths are relative to your deployment's API host.

GET /api/skill-registry-api/skills/{id}/governance

The governance state of a skill.

Lifecycle state, risk tier + the deterministic indicators that fired, eval-suite status, approval provenance, and the append-only audit history of the current version.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/skill-registry-api/skills/{id}/governance/approve

Approve the skill.

Transitions in_review → approved. Blocked unless the caller differs from the author (separation of duties) and the evaluation suite has a passing run.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/skill-registry-api/skills/{id}/governance/deprecate

Deprecate an approved skill.

Transitions approved → deprecated.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/skill-registry-api/skills/{id}/governance/eval-suite

Read the skill's evaluation suite.

The 3–5 representative queries plus the last-run outcome.

Authentication: bearer token (Authorization: Bearer <token>)

PUT /api/skill-registry-api/skills/{id}/governance/eval-suite

Replace the skill's evaluation suite.

Submit 3–5 representative queries (should-trigger / should-not-trigger / edge). Allowed only while the skill is in draft. Replacing the suite clears the last-run outcome.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json UpsertSkillEvalSuiteDto

GET /api/skill-registry-api/skills/{id}/governance/eval-suite/latest-run

Read the skill's latest evaluation run.

The most recent eval run with its per-case results, the aggregated benchmark, and the frozen governance-gate verdict.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/skill-registry-api/skills/{id}/governance/eval-suite/run

Run the skill's evaluation suite.

Executes a full eval-driven iteration: every test case is run twice — once with the skill mounted, once without it (the baseline) — in ephemeral sandbox sessions; every assertion is graded PASS/FAIL with concrete evidence; an aggregated benchmark (per-config pass rates + the with/without delta) is persisted. A run whose benchmark satisfies the governance gate (with-skill pass rate ≥ threshold AND positive delta) is what approve requires.

Authentication: bearer token (Authorization: Bearer <token>)

GET /api/skill-registry-api/skills/{id}/governance/history

Read the skill's immutable revision history.

Returns every server-numbered revision newest first, including content identity, source provenance, lifecycle state, and live/draft pointers.

Authentication: bearer token (Authorization: Bearer <token>)

POST /api/skill-registry-api/skills/{id}/governance/reject

Reject the skill under review.

Transitions in_review → draft so the author can revise. A reason is required and recorded on the audit log.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json RejectSkillDto

POST /api/skill-registry-api/skills/{id}/governance/restore

Fork a historical skill revision into a new editable draft.

NOT the way to go back — use POST …/governance/rollback for that. This copies the exact historical SKILL.md, metadata and resources into a NEW server-numbered draft so it can be edited. The live revision is unchanged, and because the copy has a new revision id no evaluation run is pinned to it: the draft must clear the full gate (submit, a fresh eval run, and an approver who is not its author) before it can be served.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json RestoreSkillRevisionDto

POST /api/skill-registry-api/skills/{id}/governance/rollback

Roll the stable channel back to a previously released revision.

Submits an audited Resource Governance rollback using the immutable ReleaseSet that previously promoted targetRevisionNumber. It creates no revision, copies no bytes, re-runs no evaluation and does not touch the working draft. Policy, Decision and stable-channel compare-and-swap are owned by the unified release plane. The request is refused when no matching retained ReleaseSet exists or when governance rejects the promotion.

Authentication: bearer token (Authorization: Bearer <token>)

Request body: application/json RollbackSkillRevisionDto

POST /api/skill-registry-api/skills/{id}/governance/submit-for-review

Submit the skill for review.

Transitions the current version draft → in_review.

Authentication: bearer token (Authorization: Bearer <token>)