Skill Registry API: schemas

The request and response bodies of the operations in this API.

CreateSkillBundleDto

Property	Type	Required	Description
`resources`	array of CreateSkillBundleResourceDto	yes	Every non-SKILL.md bundle file. A nested `SKILL.md` resource declares a sub-skill. Pass an empty array for a SKILL.md-only bundle.
`scope`	SpaceKind	yes	Authoring scope — only `org`, `project`, or `user`.
`skillMarkdown`	string	yes	Raw SKILL.md content (YAML frontmatter + body). Frontmatter is strictly validated — `name` and `description` are required.
`slug`	string	yes	Hierarchical slug, e.g. `software-engineering/requirements`.

CreateSkillBundleResourceDto

Property	Type	Required	Description
`contentBase64`	string (base64)	yes	File bytes, base64-encoded.
`relPath`	string	yes	Forward-slash path relative to the skill directory, e.g. `reference/api.md` or `scripts/lint.sh`. No leading slash, no `..` segments.
`type`	SkillResourceType	yes	Classification of the file. The server re-derives this deterministically from `relPath`; the supplied value documents author intent.

CreateSkillBundleResponseDto

Property	Type	Required	Description
`contentHash`	string	yes	SHA-256 content hash of the top-level skill bundle.
`ingestedSkillSlugs`	array of string	yes	Slugs of every skill written by this call — the top-level skill plus any nested sub-skills, parents first.
`revisionNumber`	number	yes	Server-generated revision number of the top-level skill.
`skillId`	string	yes	Id of the top-level skill the bundle authored.
`slug`	string	yes	Slug of the top-level skill.

CreateSkillBundleResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	CreateSkillBundleResponseDto	yes

CreateSkillDto

Property	Type	Required	Description
`category`	string	no	Free-form grouping tag.
`description`	string	yes	What the skill does + when to use it. Drives discovery.
`injectionMode`	SkillInjectionMode	no
`kind`	SkillKind	no
`name`	string	yes	SKILL.md `name` — lowercase letters, numbers, hyphens.
`parentSlug`	string	no	Parent skill slug when creating a nested sub-skill.
`scope`	SpaceKind	yes	Authoring scope — only `org`, `project`, or `user`.
`skillMarkdown`	string	yes	Raw SKILL.md content (frontmatter + body).
`slug`	string	yes	Hierarchical slug, e.g. `software-engineering/requirements`.
`tags`	array of string	no

CreateSkillRepositoryDto

Property	Type	Required	Description
`ref`	string	no	Branch, tag, or commit to ingest. Defaults to the repo default branch.
`rootPath`	string	no	Sub-directory to scan for SKILL.md bundles. Defaults to the repo root.
`url`	string (uri)	yes	HTTP(S) clone URL of the git repository.

EvaluationVerdict

Type: one of "pass", "fail"

ExactSkillRevisionAuthorityResponseDto

Property	Type	Required	Description
`bundle`	SkillBundleResponseDto	yes
`content`	ExactSkillRevisionContentDto	yes	Canonical stored revision content. Consumers recompute contentHash with the kernel Skill revision hash contract.
`contentHash`	string (sha256)	yes
`contentHashVersion`	one of `2`	yes
`ownerSpaceRef`	SkillOwnerSpaceRefDto	yes
`resourceId`	string	yes
`revisionId`	string	yes
`revisionNumber`	number	yes

ExactSkillRevisionAuthorityResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	ExactSkillRevisionAuthorityResponseDto	yes

ExactSkillRevisionContentDto

Property	Type	Required	Description
`dependencies`	array of object	yes
`resources`	array of SkillBundleResourceDto	yes
`schemaVersion`	one of `2`	yes
`skillMarkdown`	string	yes	Stored SKILL.md body before mount-time frontmatter rendering.

ProblemActionableBy

Who can act on this refusal: user (correct the input, sign in), org-admin (an administrator of the organisation), platform (the operators of this installation), none (nobody — it cannot succeed). ABSENT when not known; never guessed.

Type: one of "user", "org-admin", "platform", "none"

ProblemDetailsDto

RFC 9457 problem document. The declared members are the reserved core; extension members are TOP-LEVEL and OPEN, owned by the refusing plane.

Property	Type	Required	Description
`actionableBy`	ProblemActionableBy	no	Who can act on this refusal: `user` (correct the input, sign in), `org-admin` (an administrator of the organisation), `platform` (the operators of this installation), `none` (nobody — it cannot succeed). ABSENT when not known; never guessed.
`code`	string	yes	SCREAMING_SNAKE_CASE. The machine-branchable refusal, and the value a policy rule, a retry predicate and a UI branch all name.
`detail`	string	no	Human-readable and specific to THIS occurrence.
`errors`	array of ProblemFieldIssueDto	no	Field-level issues, when the refusal is about the request body.
`instance`	string	no	URI reference identifying the occurrence — a request path, a run, a row.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for the message keyed by `code` — typed and allowlisted per code by its declaration. Never server-authored copy, never internal diagnostics.
`retry`	ProblemRetry	no	What a retry can achieve: `transient` (later, unchanged), `after-change` (only after someone changes something), `never` (a defect until a fixed version ships). ABSENT when not known.
`status`	number	yes	The HTTP status code, repeated in the body so a logged document is self-contained.
`title`	string	yes	Short, human-readable, and STABLE for a given `type`. Never per-occurrence — that is `detail`.
`traceId`	string	no	W3C trace-context trace-id, present when the caller sent a `traceparent`. Omitted rather than invented when it did not.
`type`	string	yes	Absolute URI identifying the refusal TYPE. Derived one-to-one from `code`, so a caller may branch on either and can never be told two different things. Never `about:blank`.

ProblemFieldIssueDto

Property	Type	Required	Description
`code`	string	no	SCREAMING_SNAKE_CASE code of THIS issue, for a frontend i18n key. Present when the issue was minted by a declared problem.
`detail`	string	yes	Prose for logs and developers. A frontend localises from `code` + `params` instead.
`params`	map of string or number or boolean	no	Safe i18n interpolation values for this issue's `code`.
`pointer`	string	yes	RFC 6901 JSON Pointer into the request body. Root is "/".

ProblemRetry

What a retry can achieve: transient (later, unchanged), after-change (only after someone changes something), never (a defect until a fixed version ships). ABSENT when not known.

Type: one of "transient", "after-change", "never"

RejectSkillDto

Property	Type	Required	Description
`reason`	string	yes	Why the skill version was rejected.

RescopeSkillDto

Property	Type	Required	Description
`targetProjectId`	string	no	Project that becomes the new owner. REQUIRED when `targetScope = project`; rejected for any other target.
`targetScope`	SpaceKind	yes	Target owner tier. Must be a legal promotion of the row's current tier (`user → project\|org`, `project → org`) — demotion, same-tier, and moves into/out of `biome`/`system` are refused with 422. `app` and `session` are not tiers this registry owns at all and are refused with 400.

RestoreSkillRevisionDto

Property	Type	Required	Description
`targetRevisionNumber`	number	yes	Historical revision number to COPY into a new working draft so it can be edited. The live revision is untouched, and the copy is a NEW revision that must clear the full governance gate (review, separation of duties, and a fresh eval run) before it can be served. To simply return to this revision, use POST …/governance/rollback instead.

RollbackSkillRevisionDto

Property	Type	Required	Description
`targetRevisionNumber`	number	yes	The approved revision number to serve. Must belong to this skill, must be `approved`, and must not already be the served revision.

SearchSkillsQueryDto

Property	Type	Required	Description
`kind`	SkillKind	no
`limit`	number	no	Max results to return (1–100). Defaults to 20.
`query`	string	yes	Free-text query matched against name + description.

SetSystemSkillEnabledDto

Property	Type	Required	Description
`enabled`	boolean	yes	Disabling a MANDATORY skill is refused, not silently ignored: the baseline resolver unions the core back in regardless, so accepting it would report a change that does not happen.
`slug`	string	yes

SkillAssertionGradingMethod

Type: one of "mechanical", "llm_judge"

SkillAssertionResultDto

Property	Type	Required	Description
`assertion`	string	yes	The assertion text, copied verbatim from the test case.
`evidence`	string	yes	Concrete evidence for the verdict — a quote from the actual output or a mechanical observation. A PASS requires real evidence, never an opinion.
`method`	SkillAssertionGradingMethod	yes
`verdict`	EvaluationVerdict	yes

SkillAvailableAction

Lifecycle transitions the caller can perform on this skill now: those legal from its current lifecycle state, whose route admits the caller org role, and that separation of duties allows. Render governance actions from this list only.

Type: one of "submit_for_review", "approve", "reject", "deprecate"

SkillBundleFileMode

Type: one of "read-only", "executable"

SkillBundleResourceDto

Property	Type	Required	Description
`content`	string	yes	File bytes, base64-encoded.
`mode`	SkillBundleFileMode	yes
`relPath`	string	yes	Forward-slash path relative to the skill directory.
`sizeBytes`	number	yes	Decoded byte length of the file.
`type`	SkillResourceType	yes

SkillBundleResponseDto

Property	Type	Required	Description
`allowedTools`	string or null	yes
`compatibility`	string or null	yes
`contentHash`	string	yes	SHA-256 of the bundle; verified at mount time.
`contentHashVersion`	one of `2`	yes
`dependencies`	array of object	yes
`description`	string	yes	The skill's resolved description. Part of the mountable identity so consumers (e.g. hot skill-attach) can record it without a second metadata lookup.
`license`	string or null	yes
`metadata`	map of string	yes
`name`	string	yes
`resourceId`	string	yes	Identity of the skill resource. With `revisionId` and `contentHash` it is the exact pin the exact-revision authority resolves.
`resources`	array of SkillBundleResourceDto	yes
`revisionId`	string	yes	Identity of the revision this bundle is the content of.
`revisionNumber`	number	yes	Server-generated live revision number.
`skillMarkdown`	string	yes	Raw SKILL.md (frontmatter + body).
`slug`	string	yes

SkillBundleResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	SkillBundleResponseDto	yes

SkillCatalogEntryDto

Property	Type	Required
`category`	string or null	yes
`description`	string	yes
`kind`	SkillKind	yes
`name`	string	yes
`slug`	string	yes
`tags`	array of string	yes

SkillCatalogEntryDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of SkillCatalogEntryDto	yes

SkillEvalBenchmarkDto

Property	Type	Required	Description
`passRateDelta`	number	yes	withSkill.passRate - withoutSkill.passRate. Positive = helps.
`totalDurationMsDelta`	number	yes	withSkill.totalDurationMs - withoutSkill.totalDurationMs.
`totalTokensDelta`	number	yes	withSkill.totalTokens - withoutSkill.totalTokens. Positive = costs.
`triggeringAccuracyDelta`	number	yes	withSkill.triggeringAccuracy - withoutSkill.triggeringAccuracy.
`withSkill`	SkillEvalConfigBenchmarkDto	yes
`withoutSkill`	SkillEvalConfigBenchmarkDto	yes

SkillEvalCaseDto

Property	Type	Required	Description
`assertions`	array of string	yes	Verifiable, specific, observable statements graded against the actual output (e.g. "The output file is valid JSON", "The report includes at least 3 recommendations"). Not vague, not brittle exact-phrase matches.
`expectedOutput`	string	yes	Human-readable description of what a successful output looks like.
`files`	array of SkillEvalCaseFileDto	no	Optional input files seeded into the sandbox /workspace/ before the run.
`id`	string	yes	Author-supplied stable identifier, unique within the suite.
`prompt`	string	yes	A realistic user message — the prompt sent to the agent.
`triggerExpectation`	SkillTriggerExpectation	yes	Whether the skill is expected to load into context for this prompt.

SkillEvalCaseFileDto

Property	Type	Required	Description
`content`	string	yes	UTF-8 file content.
`path`	string	yes	Forward-slash path relative to /workspace/.

SkillEvalCaseResultDto

Property	Type	Required	Description
`assertionResults`	array of SkillAssertionResultDto	yes
`caseId`	string	yes
`config`	SkillEvalRunConfig	yes
`durationMs`	number	yes	End-to-end turn duration in milliseconds.
`gradingFailed`	number	yes	Assertions that failed.
`gradingPassRate`	number	yes	passed / total, in [0, 1].
`gradingPassed`	number	yes	Assertions that passed.
`gradingTotal`	number	yes	Total assertions graded.
`output`	string	yes	The agent’s final assistant reply text.
`skillTriggered`	boolean	yes	Whether the skill under test actually loaded into context.
`totalTokens`	number	yes	Sum of input + output tokens across the turn.
`triggeringCorrect`	boolean	yes	Whether observed triggering matched the case expectation.

SkillEvalConfigBenchmarkDto

Property	Type	Required	Description
`config`	SkillEvalRunConfig	yes
`passRate`	number	yes	Mean assertion pass rate across all cases, in [0, 1].
`totalDurationMs`	number	yes	Total wall-clock duration summed across every case (ms).
`totalTokens`	number	yes	Total tokens summed across every case.
`triggeringAccuracy`	number	yes	Fraction of cases whose triggering matched expectation.

SkillEvalRunConfig

Type: one of "with_skill", "without_skill"

SkillEvalRunResponseDto

Property	Type	Required	Description
`benchmark`	SkillEvalBenchmarkDto or null	yes	Aggregated benchmark; null until the run completes.
`caseResults`	array of SkillEvalCaseResultDto	yes
`completedAt`	string or null	yes
`failureReason`	string or null	yes	Failure detail when status is `failed`; null otherwise.
`gatePassed`	boolean or null	yes	Whether this run satisfies the governance gate (with-skill pass rate ≥ threshold AND positive delta). Null while running / on failure.
`iteration`	number	yes	Which iteration of the eval-driven loop this run is.
`runId`	string	yes
`skillId`	string	yes
`startedAt`	string	yes
`status`	SkillEvalRunStatus	yes

SkillEvalRunResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	SkillEvalRunResponseDto	yes

SkillEvalRunStatus

Type: one of "running", "completed", "failed"

SkillEvalSuiteResponseDto

Property	Type	Required	Description
`baselineAgentId`	string	yes
`cases`	array of SkillEvalCaseDto	yes
`nextIteration`	number	yes	The iteration number the NEXT eval run will be recorded as.
`skillId`	string	yes

SkillEvalSuiteResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	SkillEvalSuiteResponseDto	yes

SkillGovernanceAction

Type: one of "submit_for_review", "approve", "reject", "deprecate", "restore_to_draft", "rollback"

SkillGovernanceEventDto

Property	Type	Required
`action`	SkillGovernanceAction	yes
`actorId`	string	yes
`createdAt`	string	yes
`fromState`	SkillLifecycleState	yes
`note`	string or null	yes
`toState`	SkillLifecycleState	yes

SkillGovernanceStateDto

Property	Type	Required	Description
`approvedById`	string or null	yes
`contentHash`	string	yes
`createdById`	string or null	yes
`hasEvalSuite`	boolean	yes	Whether an evaluation suite has been submitted.
`history`	array of SkillGovernanceEventDto	yes
`latestEvalGatePassed`	boolean or null	yes	Whether the LATEST eval run satisfies the governance gate; null when no suite, no run, or the latest run is still running / failed.
`latestEvalIteration`	number or null	yes	Iteration number of the latest eval run; null when no run exists.
`lifecycleState`	SkillLifecycleState	yes
`requiresExplicitApproval`	boolean	yes	Whether this tier mandates an explicit human approval.
`revisionNumber`	number	yes
`riskIndicators`	array of SkillRiskIndicator	yes	Deterministic indicators that fired during the risk scan.
`riskTier`	SkillRiskTier	yes
`skillId`	string	yes
`stableRevisionNumber`	number or null	yes

SkillGovernanceStateDtoDataEnvelope

Property	Type	Required	Description
`data`	SkillGovernanceStateDto	yes

SkillInjectionMode

Type: one of "always", "context_dependent"

SkillKind

Type: one of "procedural", "deliverable", "system"

SkillLifecycleState

Type: one of "draft", "in_review", "approved", "deprecated"

SkillOwnerSpaceDto

Property	Type	Required
`biomeId`	string	no
`orgId`	string	no
`projectId`	string	no
`tier`	one of `"system"`, `"org"`, `"project"`, `"app"`, `"session"`, `"biome"`, `"user"`	yes
`userId`	string	no

SkillOwnerSpaceRefDto

Property	Type	Required
`fence`	one of `"global"`, `"tenant"`	yes
`orgId`	string or null	yes
`space`	SkillOwnerSpaceDto	yes

SkillRepositoryResponseDto

Property	Type	Required	Description
`createdAt`	string	yes
`id`	string	yes
`lastSyncedAt`	string or null	yes
`lastSyncedRef`	string or null	yes	Resolved commit sha of the last successful sync.
`ref`	string or null	yes
`rootPath`	string or null	yes
`updatedAt`	string	yes
`url`	string	yes

SkillRepositoryResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of SkillRepositoryResponseDto	yes

SkillRepositoryResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	SkillRepositoryResponseDto	yes

SkillRepositorySyncResultDto

Property	Type	Required	Description
`ingestedSkillSlugs`	array of string	yes	Slugs of skills created or updated by this sync.
`removedSkillSlugs`	array of string	yes	Slugs removed because they no longer exist in the repo.
`repositoryId`	string	yes
`resolvedRef`	string	yes	Resolved commit sha actually ingested.
`syncedAt`	string	yes

SkillRepositorySyncResultDtoDataEnvelope

Property	Type	Required	Description
`data`	SkillRepositorySyncResultDto	yes

SkillResourceType

Type: one of "reference", "script", "asset", "template", "sub_skill"

SkillResponseDto

Property	Type	Required	Description
`availableActions`	array of SkillAvailableAction	yes	Lifecycle transitions the caller can perform on this skill now: those legal from its current lifecycle state, whose route admits the caller org role, and that separation of duties allows. Render governance actions from this list only.
`biomeId`	string or null	yes	The biome that contributed this skill; null for a skill no biome contributed. The value `?biomeId=` filters on.
`category`	string or null	yes
`contentHash`	string or null	yes
`createdAt`	string	yes
`description`	string	yes
`draftRevisionNumber`	number or null	yes	Working draft revision number; null when no draft exists.
`id`	string	yes
`injectionMode`	SkillInjectionMode	yes
`kind`	SkillKind	yes
`lifecycleState`	SkillLifecycleState or null	yes
`name`	string	yes
`parentSlug`	string or null	yes	Parent skill slug; null for a top-level skill.
`policyRevision`	number or null	yes	Monotonic authorization policy revision that bracketed availableActions; null when no policy was evaluated (a role-gate projection, which this one is).
`requiredCapabilities`	array of string	yes	CapabilityRef strings this skill needs to drive the tools it orchestrates (`SkillFrontmatter.requiredCapabilities`). Empty for most procedural skills. When an armed skill declares some, the llm-registry auto-grant engine unions them into the required-capability manifest of the arming agent.
`revisionNumber`	number or null	yes	Server-generated live revision number; null before approval.
`riskTier`	SkillRiskTier or null	yes
`scope`	SpaceKind	yes
`skillMarkdown`	string or null	yes	Raw SKILL.md — present on single-skill reads, null in lists.
`slug`	string	yes	Hierarchical slug, e.g. `software-engineering/requirements`.
`sourceKind`	SkillSourceKind	yes
`surfaces`	array of SkillSurface or null	yes	Optional surface gate. `null` = applies to BOTH surfaces (the default). A non-null array lists the surfaces this skill applies to; the always-on resolver filters by this against the requesting surface.
`tags`	array of string	yes
`updatedAt`	string	yes
`upstreamChangedSinceFork`	boolean or null	yes	For a customer fork of a contributed skill: true when a push has delivered a revision newer than the one the fork was taken from. Null when the skill is not a fork.

SkillResponseDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of SkillResponseDto	yes

SkillResponseDtoDataEnvelope

Property	Type	Required	Description
`data`	SkillResponseDto	yes

SkillRevisionHistoryEntryDto

Property	Type	Required	Description
`approvedAt`	string or null	yes
`contentHash`	string	yes
`createdAt`	string	yes
`id`	string	yes
`isDraft`	boolean	yes	Whether this revision is the current working draft.
`isLive`	boolean	yes	Whether this revision is the currently live revision.
`lifecycleState`	SkillLifecycleState	yes
`restoredFromRevisionNumber`	number or null	yes	Historical revision copied to create this draft; null for authored/source revisions.
`revisionNumber`	number	yes
`riskTier`	SkillRiskTier	yes
`sourceRevision`	string or null	yes

SkillRevisionHistoryEntryDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of SkillRevisionHistoryEntryDto	yes

SkillRiskIndicator

Deterministic indicators that fired during the risk scan.

Type: one of "script_resource", "mcp_tool_reference", "network_call", "path_traversal", "hardcoded_credential", "shell_invocation"

SkillRiskTier

Type: one of "low", "medium", "high"

SkillSourceKind

Type: one of "system", "biome", "authored", "git_repo"

SkillSurface

Type: one of "workflow", "agent-session"

SkillTreeNodeDto

Property	Type	Required	Description
`children`	array of SkillTreeNodeDto	yes
`skill`	SkillResponseDto	yes

SkillTreeNodeDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of SkillTreeNodeDto	yes

SkillTriggerExpectation

Whether the skill is expected to load into context for this prompt.

Type: one of "should_trigger", "should_not_trigger"

SpaceKind

Type: one of "system", "org", "project", "app", "session", "biome", "user"

StringDataArrayEnvelope

Property	Type	Required	Description
`data`	array of string	yes

SystemSkillBaselineEntryDto

Property	Type	Required	Description
`enabled`	boolean	yes	Whether this org mounts it. Always true for a mandatory skill — reporting otherwise would contradict what the running system does.
`mandatory`	boolean	yes	Mounted for every agent regardless of configuration. An agent without it cannot function, so it cannot be disabled — the toggle is shown read-only rather than hidden, so its presence in every session is explained rather than mysterious.
`name`	string	yes
`slug`	string	yes

SystemSkillBaselineEntryDtoDataArrayEnvelope

Property	Type	Required	Description
`data`	array of SystemSkillBaselineEntryDto	yes

UpdateSkillDto

Property	Type	Required	Description
`category`	string	no
`description`	string	no
`injectionMode`	SkillInjectionMode	no
`name`	string	no
`skillMarkdown`	string	no	New SKILL.md content. When changed, a server-numbered draft revision is created.
`tags`	array of string	no

UpsertSkillEvalSuiteDto

Property	Type	Required	Description
`baselineAgentId`	string	yes	llm-registry-api Agent id of the GENERIC baseline composition the eval runs against. Both A/B configs use this composition; the with-skill config additionally mounts the skill under test. Pick a generic agent composition with no domain skills so the delta isolates THIS skill.
`cases`	array of SkillEvalCaseDto	yes