Templates and Skills

On this page

Before you begin
Use the current versioning model
Distinguish drafts and versions
1. Publish an immutable snapshot
Understand latest-version display
2. Pin an exact version to an Agent
Pin exact versions in Templates and Overrides
3. Recover an affected Agent safely
Inspect immutable version history
Protect referenced versions
Distinguish version and lineage deletion
Apply safe cleanup rules
Use the correct scoped version route
Troubleshooting
Recommended practices
Next steps

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.

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

Validate the complete draft file set.
Require exactly one root SKILL.md.
Snapshot draft files, description, provider requirements, and source provenance.
Create the next immutable published version.
Apply published metadata to the lineage’s current summary.
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

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 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:

Select an earlier published version for the affected Agent.
Apply the new exact pin.
Restart or apply the Agent configuration through the normal Agent workflow when required.
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.