Skill Versions

Each skill has ordered versions (skillVersionSchema). Versions are the unit of immutability: you change behavior by creating a new version, not by editing a published one.

Fields that matter at runtime

• layers - promptLayerSchema[] (type base/task/policy/format/override, mode append/replace, content).
• tools - bound tool versions with optional capability metadata (skillVersionToolSchema).
• inputSchema / variablesSchema / outputSchema - JSON Schema payloads for validation and UI.
• executionReadiness - runnable, blockingIssues, requiredProviderKeys (executionReadinessSchema).
• preview - rendered prompt + composition trace for authoring and validation.

Draft vs published

Draft versions are editable and used for preview and evaluations. Published versions are the stable baseline for runs. When skillVersionId is omitted on POST /api/skills/:id/run, the runtime resolves the current published version.

See also

• Draft vs. Published
• Version Identity