--- title: Manage Skill versions canonical: "https://agentbarn.dev/guides/templates-and-skills/skill-versions" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-02T11:46:37.000Z" author: Agent Barn description: "Understand Skill drafts, immutable publications, exact Agent and Template pins, per-Agent recovery, and protected version and lineage deletion." tags: [Templates and Skills, Concept, "Skill authors, Agent operators, and Organization administrators", Skill versions, Skill draft, publish Skill, Skill pin, exact Skill version, delete Skill version, Skill lineage deletion, version history, required providers, immutable snapshot] categories: [Guides, Templates and Skills] --- - Templates and Skills - 12–15 minutes Skill Versions are immutable release artifacts. Drafts hold the next proposed snapshot; Agents, Templates, and Agent Template Overrides retain exact published-version pins until someone changes them deliberately. **Publishing and adoption are separate** Publishing creates a new immutable version. It never updates an existing Agent assignment, Template requirement, or Agent Template Override requirement, and it does not restart an Agent. ## Before you begin - Platform Skill versions are managed by Platform Administrators. - Organization Skill reads require `skill.read`; draft, publish, and deletion actions require `skill.manage`. - Agent-private Skill operations require access to the owning Agent and the matching Agent permission. - Use Agent Configuration to explicitly repin an Agent when adoption or recovery requires it. A visible Platform Skill remains read-only from an Organization or Agent scope unless it is forked into that scope. Another Agent’s private history is never visible. ## Use the current versioning model ``` Create lineage ↓ Initial unpublished draft ↓ Publish ↓ Immutable version 1 ↓ Start another draft from latest ↓ Publish ↓ Immutable version 2 ``` ``` Skill lineage ├── stable identity and display name ├── immutable slug and stable mount directory ├── scope and ownership ├── at most one mutable draft └── zero or more immutable published versions ``` A newly created Skill has a stable lineage and an initial unpublished draft, not version `1`. The first successful publish creates version `1`; a later draft for a published Skill is seeded from the latest published version. ## Distinguish a draft from a published version | Draft | Published version | | --- | --- | | Mutable | Immutable | | At most one per lineage | Multiple snapshots per lineage | | May exist without a published version | Has an assigned version number | | Not mounted by Agents | Can be pinned and mounted | | Can be saved or discarded | Can only be viewed or safely deleted | | Holds staged files and metadata | Holds an exact file and metadata snapshot | | Cleared after publishing | Retained in version history | Saving a draft does not affect published consumers. Discarding a draft leaves every published version unchanged. Historical content is never edited in place: make changes through a new draft, then publish another version. ## Publish a complete immutable snapshot 1. Validate the complete draft file set. 2. Require exactly one root `SKILL.md`. 3. Snapshot draft files, description, provider requirements, and source provenance. 4. Create the next immutable published version. 5. Apply published metadata to the lineage’s current summary. 6. Delete the mutable draft. Each published version contains its number, creator metadata, publication time, description, required providers, source Skill ID and version when applicable, complete UTF-8 file tree, and one root `SKILL.md`. Supporting paths are relative to the Skill root. ``` Skill version 3 ├── SKILL.md └── references/ ├── setup.md └── commands.md ``` **What publishing does not do** It does not mutate earlier versions, merge another draft, change the immutable slug or mount directory, update consumer pins, or restart an Agent. ## Understand latest-version display The latest published version is the highest currently published version number for the lineage. There is no mutable “current version” pointer that rewrites older snapshots. When the UI opens a Skill without a selected historical version, it displays that latest published snapshot; display behavior never changes an Agent or Template pin. ## Pin an exact version to an Agent ``` Agent assignment ├── skill_id └── pinned_version ``` - An Agent may select a specific published version. - If a version is omitted, Agent Barn resolves and persists the latest published version at apply time. - Publishing another version never moves existing pins; two Agents can intentionally use different versions. - An unpublished draft cannot be mounted. - Runtime start mounts the exact version persisted on the Agent assignment. The Skills section of [Agent Configuration](/guides/agents/configuration) exposes the version selector. Re-pinning is explicit and does not alter other Agents. ## Pin exact versions in Templates and Overrides Templates and Agent Template Overrides preserve the exact Skill Version selected when they are created: ``` skill_id + skill_version ``` Publishing another Skill Version does not mutate existing Template Versions or Override requirements. Template and Override drafts that reference a Skill Version protect it from deletion. Adopting a newer Skill requires an explicit Template, Override, or Agent change. ## Recover an affected Agent safely There is no Restore Version or Restore as Draft workflow. Recovery from a problematic version is a per-Agent decision: 1. Select an earlier published version for the affected Agent. 2. Apply the new exact pin. 3. Restart or apply the Agent configuration through the normal Agent workflow when required. 4. Leave other Agents on their current versions unless they also need recovery. To correct shared Skill content, start a new draft, make the correction, publish a new immutable version, explicitly repin affected Agents, update relevant Template or Override requirements, then delete the bad version only after all references are removed. Do not republish an old snapshot globally merely to recover one Agent. ## Inspect immutable version history Version history is listed newest first. Each entry can show the version number, publication information, required providers, source provenance, immutable files, whether an Agent pins it, and whether deletion is currently available. Selecting historical content displays that exact metadata and file tree without edit mode. Starting a draft or publishing another version never mutates historical snapshots. ## Protect referenced versions A version can be deleted only when all of these are true: - The lineage has at least one other published version. - No Agent pins the version. - No Platform or Organization Template, including their drafts, requires it. - No Agent Template Override Version or draft requires it. - No Skill Draft references it as a source. - No published fork version references it as a source. A protected deletion returns a conflict and leaves the version and all of its files unchanged. Remove or update each referencing resource before retrying; deletion never silently repins consumers. ### What version deletion removes It removes that immutable `skill_version` snapshot and its `skill_file` rows. It does not remove the lineage, other versions, the current draft, assignments to other versions, other Template requirements, or forks derived from another source version. An eligible historical-version deletion does not alter Runtime mounts because mounts use exact persisted pins. ## Distinguish version deletion from lineage deletion | Operation | Result | Main constraints | | --- | --- | --- | | Delete version | Removes one immutable snapshot and its files | Cannot be the only version or have any references | | Delete Skill | Removes a complete custom lineage, draft, all versions, and all files | Must be custom, owned by the caller’s scope, and completely unused | Whole-lineage deletion is blocked by Agent assignments, Template requirements, Agent Template Override requirements, and published or draft fork provenance. Pins retained for soft-deleted Agents also block it. Built-in `aai_cli` lineages cannot be deleted. ## Apply safe cleanup rules ``` Skill: Incident response Published versions: v1, v2, v3 Agent A pins v2 Agent B pins v3 A Template requires v2 ``` - `v1` may be deleted only if it has no other references. - `v2` cannot be deleted until Agent A and the Template stop referencing it. - `v3` cannot be deleted while Agent B pins it. - The only remaining version can never be deleted. - Publishing `v4` does not move Agent A or Agent B automatically. ## Use the correct scoped version route | Scope | List versions | | --- | --- | | Platform | `/api/v1/platform/skills/{skill_id}/versions` | | Organization | `/api/v1/organizations/{organization_id}/skills/{skill_id}/versions` | | Agent-private | `/api/v1/organizations/{organization_id}/agents/{agent_id}/skills/{skill_id}/versions` | ``` Platform GET /api/v1/platform/skills/{skill_id}/versions GET /api/v1/platform/skills/{skill_id}/versions/{version} DELETE /api/v1/platform/skills/{skill_id}/versions/{version} Organization GET /api/v1/organizations/{organization_id}/skills/{skill_id}/versions GET /api/v1/organizations/{organization_id}/skills/{skill_id}/versions/{version} DELETE /api/v1/organizations/{organization_id}/skills/{skill_id}/versions/{version} Agent-private GET /api/v1/organizations/{organization_id}/agents/{agent_id}/skills/{skill_id}/versions GET /api/v1/organizations/{organization_id}/agents/{agent_id}/skills/{skill_id}/versions/{version} DELETE /api/v1/organizations/{organization_id}/agents/{agent_id}/skills/{skill_id}/versions/{version} ``` The draft lifecycle beneath the appropriate prefix is: ``` GET /{skill_id}/draft POST /{skill_id}/draft PATCH /{skill_id}/draft DELETE /{skill_id}/draft POST /{skill_id}/draft/publish ``` Do not use an Organization mutation route for a Platform or Agent-private Skill. Authorization is evaluated before deletion checks, and management permission never bypasses reference protection. ## Troubleshooting ### A published version did not change an Agent Expected exact pin Publishing never moves an Agent pin. Select the required published version in Agent Configuration and apply the change explicitly. ### A draft opened instead of a new editor One draft per lineage Only one mutable draft may exist. Review, save, discard, or publish the existing draft before continuing. ### A version cannot be deleted Reference protection Check Agent pins, Platform and Organization Template versions and drafts, Override versions and drafts, Skill-draft provenance, and fork provenance. Remove the reference first; do not force-delete. ### I need to correct shared content Publish forward Start a new draft, publish a corrected immutable version, and explicitly repin only the affected consumers. Historical versions stay read-only. ## Recommended practices - Treat each published version as a release artifact with a complete file snapshot. - Test a new pin with a non-production Agent before wider repinning. - Record exact Skill IDs and versions in incident and rollout notes. - Publish corrections forward, and prune only history with no remaining references. - Keep provider credentials, permissions, and Communication Connection credentials outside Skill Version files. ## Next steps - [Work with Skills](/guides/templates-and-skills/skills) - [Forks and Updates](/guides/templates-and-skills/forks-and-updates) - [Skill scopes and Template concepts](/guides/templates-versions-and-skills) - [Work with Templates](/guides/templates-and-skills/templates) and [Template Versions](/guides/templates-and-skills/template-versions) - [Use Agent Overrides](/guides/templates-and-skills/agent-overrides) and [configure an Agent](/guides/agents/configuration)