Templates and Skills

On this page

Before you begin
How Skill versioning works
Versioned and lineage fields
Latest and current
Create the initial version
Understand the draft lifecycle
1. Start and save a draft
2. Publish a version
Choose the correct action
Test and release a version
3. Apply a version to an Agent
4. Roll back an Agent
5. Make historical files current
View version history
Version deletion rules
6. Delete a version
Providers across publications
Draft metadata behavior
Built-in Skill versions
API reference
Troubleshooting
Recommended practices
Next steps

Templates and Skills
12–15 minutes

Skill versions let you improve a Skill without changing the files mounted by Agents that already use it.

Every published version is an immutable snapshot of the Skill’s files. Each Agent pins an exact version and keeps that pin until someone explicitly changes it.

Before you begin

You need:

skill.read permission to view Skills and version history
skill.manage permission to edit, publish, discard, or delete Custom Skill versions
Access to the Agent when reviewing assignments
agent.update permission to change an Agent’s Skill version
A stopped Agent when changing its assignment or version pin

If you have not created or assigned a Skill before, begin with Work with Skills.

How Skill versioning works

A Skill is a stable lineage with one or more published file snapshots.

Skill Draft
Publish
Immutable Version
Explicit Agent pin

Skill lineage: Incident Triage
Skill ID: 6fd2f967-0d12-477a-8af1-a90dbfca87a3

v1 ───────── v2 ───────── v3
 │             │            │
 └─ Agent A    └─ Agent B    └─ Latest published version

The lineage owns stable identity and mount information, including the Skill ID, name, slug, root directory, entry path, and source. Each version owns an immutable set of files.

An Agent assignment combines the lineage with a version pin:

Agent Skill assignment
├── Skill ID: 6fd2f967-0d12-477a-8af1-a90dbfca87a3
└── Pinned version: 2

Versioned and lineage-level fields

Skill files are versioned as immutable snapshots. Some metadata belongs to the Skill lineage rather than an individual historical version.

Field	Boundary
Files	Immutable published version
Version number	Immutable published version
Publication author and time	Immutable published version
Name	Skill lineage
Slug	Stable Skill lineage
Root directory	Stable Skill lineage
Entry path	Stable Skill lineage
Description	Staged in draft, applied to lineage on publish
Required providers	Staged in draft, applied to lineage on publish

This distinction matters during rollback. Repinning an Agent to an older version restores the older file set. It does not restore a historical Skill name, description, root directory, or provider requirement configuration.

Latest and current

A Skill does not store a separate current-version pointer. The highest existing published version is considered both latest and current.

Agents do not automatically use the current version. They use their exact pins.

v1 Earliest published file snapshot
- Agent A
v2 Previous file snapshot
- Agent B
v3 Latest published version — Current
- Agent C

Create the initial version

Creating a Custom Skill immediately publishes version 1. The initial request must include a name, at least one file, and SKILL.md, plus an optional description and optional required providers.

After version 1, all file changes use the draft-and-publish workflow.

Understand the draft lifecycle

Each Custom Skill can have one in-progress draft.

Latest published version Seeds the draft when one is started
Unpublished draft Save more changes, discard it, or publish it
Next immutable version Publishing copies the complete draft file set

Starting a draft returns the existing draft if one is already open. Otherwise it copies the latest published file set, the current description, and the current required providers. It does not change the published Skill, and it does not affect Agent pins.

The draft is shared at the Skill-lineage level, not private to an individual author.

Start and save a Skill Draft

To begin another version:

Open your organization.
Go to Settings.
Select Skills.
Open a Custom Skill.
Confirm the current published version.
Select Edit.
Review the draft seeded from the latest version.

If a draft already exists, Agent Barn opens that draft instead of creating another one. Built-in Skills cannot be edited — fork a Built-in Skill to create an independent Custom Skill when customization is required.

Save a Skill Draft

While editing, you can change file paths, file contents, the description, the required providers, and the display name.

The file set saved through the draft API is a complete replacement. Suppose the draft currently contains:

Current draft files

SKILL.md
references/policy.md
references/examples.md

Next save submits

SKILL.md
references/policy.md

Then references/examples.md is removed from the draft. It remains present in older published versions, but will not appear in the next published version.

Preview or discard a draft

After saving:

Close the editor.
Switch from Published vN to Draft.
Review the staged description.
Review the required providers.
Review every file and path.
Confirm that SKILL.md references valid supporting files.
Select Edit to make another change.
Select Publish when the snapshot is ready.

The latest published version remains read-only while a draft exists.

To discard unpublished changes, switch to Draft, select Discard, and confirm Discard draft. Discarding deletes the unpublished draft and its staged file changes, leaves published versions and Agent pins unchanged, and cannot be undone.

Publish a Skill version

Open the saved draft.
Review its complete file set.
Confirm the entry point is present.
Review its description.
Review its required providers.
Select Publish.
Confirm Publish this version.

Publishing creates the next version number, copies the complete draft file set, applies the staged description and required providers, records the publishing user, clears the draft, and leaves every existing Agent pin unchanged.

Before publication

Published: v3
Draft:     In progress
Agent A:   v2
Agent B:   v3

After publication

Published: v4
Draft:     None
Agent A:   v2
Agent B:   v3

Neither Agent moves to v4 automatically.

Choose the correct version action

Goal	Correct action	Creates a version?	Changes an Agent pin?
Change Skill files	Edit and publish a draft	Yes	No
Test a published version	Repin a test Agent	No	Yes
Roll out a version	Repin each intended Agent	No	Yes
Roll back one Agent	Select an older version	No	Yes
Make historical files current again	Copy them into a draft and publish	Yes	No
Abandon unpublished work	Discard the draft	No	No
Remove unused history	Delete an unpinned version	No	No
Undo a published version globally	Not supported — repin each Agent instead

Test and release a new version

Use a controlled release process.

Start draft
Edit and save
Review snapshot
Publish version
Repin a test Agent
Canary rollout
Wider rollout

Recommended steps:

Publish the new Skill version.
Select a stopped test Agent.
Repin the assigned Skill to the new version.
Start the Agent.
Run representative tasks.
Review startup logs for mount collisions.
Verify provider-dependent workflows.
Repin a small production group.
Monitor behavior.
Repin the remaining Agents.

There is no automatic fleet-wide rollout.

Apply a Skill version to an Agent

Stop the Agent.
Open the Agent.
Go to Configuration.
Select Skills.
Find the assigned Skill.
Open its version selector.
Select the exact version.
Save the configuration.
Start the Agent.
Verify its health and logs.

Only that Agent’s pin changes.

Before

Agent A ── Incident Triage v2
Agent B ── Incident Triage v2

After updating Agent A

Agent A ── Incident Triage v3
Agent B ── Incident Triage v2

The Skill’s required provider configuration is validated during relevant Agent configuration changes.

Assigning without a version

When a Skill is newly assigned and no version is supplied, Agent Barn resolves its latest published version at apply time and stores that exact number.

Latest at assignment time: v4

New Agent assignment:
Pinned version: v4

If v5 is published later, the pin remains v4. For predictable automation, provide the version explicitly.

Repin with the API

Skill pins are updated through the Agent update API.

PATCH /api/v1/organizations/{organization_id}/agents/{agent_id}
Content-Type: application/json

{
  "skill_versions": [
    {
      "skill_id": "6fd2f967-0d12-477a-8af1-a90dbfca87a3",
      "version": 3
    }
  ]
}

The requested version must exist in that Skill lineage. Stop the Agent before changing the pin, so the next start mounts the selected file snapshot.

Roll back an Agent

A Skill rollback is an Agent-level operation.

Stop the affected Agent.
Open its Skill assignments.
Select a known-good historical version.
Save the configuration.
Start the Agent.
Verify the recovered behavior.

Before rollback

Agent A ── Skill v4
Agent B ── Skill v4

After rolling back Agent A

Agent A ── Skill v2
Agent B ── Skill v4

Rollback does not create another Skill version, change other Agents, delete the problematic version, restore historical lineage metadata, change Agent Secrets, or change Template configuration.

There is no dedicated rollback endpoint. Selecting an existing version is the rollback operation.

Make historical files current again

There is no lineage-level restore endpoint. To publish historical content as the new current version:

Open Version history.
Select the historical version.
Review its files.
Retrieve or copy its complete file set.
Start a draft from the current version.
Replace the draft files with the historical file set.
Review the current description and required providers.
Save the draft.
Publish it as the next version.
Repin Agents separately if they should use it.

Current history

v1 ── v2 ── v3 ── v4
      desired       current

After republishing

v1 ── v2 ── v3 ── v4 ── v5
      desired             copied file content

Version v2 remains unchanged.

View version history

Open the Skill.
Select Version history.
Review the versions from newest to oldest.
Look for Current and Pinned by agent badges.
Select a version from the published version selector to inspect its files.

Each history entry includes the version number, its creation time, the publishing user identifier where available, and whether a live Agent pins the version. The highest existing version is marked Current.

Version deletion rules

Custom Skill removal is performed per version. There is no whole-lineage deletion operation.

A version can be deleted only when the Skill is Custom, more than one version exists, no live Agent pins that exact version, and the caller has skill.manage permission.

Version state	Deletable?
Built-in Skill version	No
Only remaining Custom version	No
Pinned by an Agent	No
Unpinned historical Custom version	Yes
Unpinned current Custom version with older history	Yes

Delete a version

To delete an unused Custom Skill version:

Open the Custom Skill.
Select Version history.
Find the version.
Confirm it is not marked Pinned by agent.
Select Delete.
Review the destructive confirmation.
Select Delete version.

If a version is pinned:

Identify the Agents using it.
Stop those Agents.
Repin them to another valid version.
Verify the Agents.
Return to the version history.
Delete the now-unpinned version.

Agent Barn also enforces the pin check at the database boundary, to protect against concurrent deletion and assignment.

Deleting the current version

The highest existing version is considered current. If the current version is unpinned and another version remains, it can be deleted. The next-highest version then becomes current.

Before deletion

Existing: v1, v2, v3
Current:  v3

Delete unpinned v3

Existing: v1, v2
Current:  v2

New publications use one more than the highest existing version. After deleting v3, the next publication may use version 3 again:

Existing after deletion: v1, v2
Next publication:        v3

Clean up a bad version safely

Publish a corrected version.
Repin affected Agents to the corrected or previous version.
Start and verify those Agents.
Confirm that no Agent pins the bad version.
Delete the bad version if historical retention is unnecessary.

Bad version:       v4
Corrected version: v5

Agent A: v4 → v5
Agent B: v4 → v3

No Agents remain on v4
        │
        ▼
Delete v4

Do not try to recover an Agent by deleting the version it currently pins. Repin first.

Required providers across publications

A draft can stage changes to required providers. The change becomes current when the draft is published.

Publishing a provider requirement change:

Does not move existing Skill pins
Does not automatically revalidate every existing Agent assignment
Affects validation during later Agent configuration changes
May require new Secrets or integration configuration

Before publishing:

Identify Agents assigned to the Skill.
Identify newly required providers.
Configure or plan the required credentials.
Publish the Skill version.
Repin and test selected Agents.
Review existing assignments for compatibility.

Removing a required provider from the Skill does not automatically remove the corresponding Agent Secret.

Draft metadata behavior

The draft stages the description, the required providers, and the files. When the draft is published, these values become the current Skill state.

The Skill name is updated directly rather than through publication. Renaming a Skill while a draft exists changes the lineage name immediately, and publishing is not required for the rename.

The slug and root directory remain unchanged.

Built-in Skill versions

Built-in aai-cli Skills are managed as global Platform Resources.

Organization users can

View the Skill
View its published files
Assign it to Agents
Pin available versions
Fork it into an independent Custom Skill

Organization users cannot

Start a Built-in Skill draft
Edit its files
Publish a Built-in version
Discard a Built-in draft
Delete a Built-in version

A Custom fork does not track later Built-in publications. It has a separate lineage and version history.

API reference

List versions

GET /api/v1/organizations/{organization_id}/skills/{skill_id}/versions

The response is ordered newest first.

[
  {
    "version": 3,
    "created_by": "93f2ed3e-567a-4497-9827-bd79ba45c15d",
    "created_at": "2026-08-29T10:20:00Z",
    "is_pinned_by_agent": false
  },
  {
    "version": 2,
    "created_by": "93f2ed3e-567a-4497-9827-bd79ba45c15d",
    "created_at": "2026-08-26T08:10:00Z",
    "is_pinned_by_agent": true
  }
]

Read one version

GET /api/v1/organizations/{organization_id}/skills/{skill_id}/versions/{version}

The response includes the version’s complete file set.

Start, read, or replace the draft

POST /api/v1/organizations/{organization_id}/skills/{skill_id}/draft

No request body is required. If a draft already exists, it is returned.

GET /api/v1/organizations/{organization_id}/skills/{skill_id}/draft

A missing draft returns 404 Not Found.

PATCH /api/v1/organizations/{organization_id}/skills/{skill_id}/draft
Content-Type: application/json

{
  "description": "Updated incident triage workflow.",
  "required_providers": [
    "jira"
  ],
  "files": [
    {
      "path": "SKILL.md",
      "content": "# Incident triage\n\nUse this workflow for production incidents."
    },
    {
      "path": "references/severity-levels.md",
      "content": "# Severity levels\n\n..."
    }
  ]
}

The files array replaces the complete draft file set. Omitting description or required_providers leaves that staged metadata unchanged. Supplying null clears the corresponding staged value.

Publish or discard the draft

POST /api/v1/organizations/{organization_id}/skills/{skill_id}/draft/publish

A successful response returns 201 Created with the Skill’s new current version.

DELETE /api/v1/organizations/{organization_id}/skills/{skill_id}/draft

A successful response returns 204 No Content.

Delete one version

DELETE /api/v1/organizations/{organization_id}/skills/{skill_id}/versions/{version}

A successful response returns 204 No Content.

Troubleshooting

I published a Skill, but the Agent still uses the old files

Publishing never moves a pin

Publishing does not move Agent pins. Stop the Agent, select the new version, save its configuration, and start it again.

The editor opened an existing draft

One draft per lineage

Only one draft can exist for a Skill lineage. The start-draft operation returns the current draft instead of replacing it.

A file disappeared from my draft

Saves replace the whole file set

Draft saves replace the complete file set. The missing file was probably omitted from a save request.

Add it back before publishing.

I cannot publish the draft

Source, permission, or validation

Check that:

The Skill is Custom
A draft exists
You have skill.manage
At least one file is present
The required entry file is present
File paths and sizes pass validation

I cannot delete a version

Protections apply

A version cannot be deleted when it belongs to a Built-in Skill, it is the only remaining version, a live Agent pins it, or you lack skill.manage.

Repin affected Agents before retrying.

Deleting the latest version changed which version is current

There is no current-version pointer

This is expected. The highest remaining version becomes current, because the lineage has no separate current-version pointer.

The next publication reused a deleted version number

Numbers come from the highest existing

New publication numbers are calculated from the highest existing version. If the highest version was deleted, its number can be used by a later publication.

Rolling back did not restore the old description

Description is lineage metadata

Agent rollback selects an older file snapshot. The description and provider requirements are current lineage-level metadata, rather than fields stored on each historical file version.

A provider change broke a later Agent update

Assignments are not revalidated

Existing assignments are not automatically revalidated when provider requirements are published. Configure the required provider credential, then retry the Agent update.

Two authors changed the same draft

Drafts have no concurrency token

Skill drafts do not use optimistic concurrency. Because each save replaces the complete file set, the later save may overwrite the earlier one.

Coordinate ownership of the draft, and review it before publication.

An old version mounts unexpected files

Check the pin, then the logs

Confirm the Agent’s exact version pin and inspect that version:

GET /api/v1/organizations/{organization_id}/skills/{skill_id}/versions/{version}

Then review startup logs for mount collisions.

Recommended practices

Treat each published version as a release artifact
Keep one author responsible for the shared draft
Review the complete file list before every save
Test with a stopped non-production Agent
Repin Agents explicitly during rollout
Use canary Agents before wider adoption
Record the exact Skill ID and version in incident notes
Roll back by selecting an existing version
Review provider requirements before publication
Revalidate affected Agents after provider changes
Publish a corrected version before deleting a bad one
Delete only history that is no longer operationally useful
Keep at least one known-good version available
Review startup logs after changing pins

Next steps

Continue to Explore integrations to learn how provider credentials and external services support Skills at runtime.