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
promptComposition- ordered prompt attachments and resolved prompt version metadata.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 plus 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.