Templates and Skills

On this page

Before you begin
How Skills work
Use the right Skill scope
Package an immutable file snapshot
1. Create and publish a Skill
Identity and mount paths
2. Assign an exact published version
Pin exact Skills in Templates and Overrides
Validate provider requirements
Understand bundled Platform Skills
3. Fork and update a Skill source
Review history and delete safely
Use the matching management surface
API reference
Troubleshooting
Recommended practices
Next steps

Templates and Skills
15 minutes

Skills are versioned bundles of instructions and supporting UTF-8 text files. A Skill lineage gives the bundle stable identity; published Skill Versions give Agents immutable content to mount.

Before you begin

skill.read reads eligible shared Skills and version history; skill.manage creates, edits, publishes, forks, applies source updates, and deletes Organization Skills.
Platform Administrators manage Platform Skills. Organization Members may use readable shared Skills but cannot mutate them.
Every Agent-private action is subordinate to the owning Agent’s corresponding access permission. Organization membership alone does not grant access to every private Skill.
Agent update authority is required to assign, remove, or repin an Agent’s Skills.

How Skills work

Skill lineage
├── stable identity
├── display name
├── immutable slug and mount directory
├── Platform, Organization, or Agent scope
├── at most one mutable draft
└── zero or more immutable published versions
    ├── exact metadata snapshot
    ├── exact provider requirements
    └── exact file snapshot

Object	Contract
Skill lineage	Stable identity, display name, immutable slug and mount directory, scope, and at most one mutable draft
Published Skill Version	Immutable metadata, provider requirements, and complete UTF-8 file snapshot
Agent assignment	Skill lineage plus one exact pinned published version
Runtime mount	The Agent’s exact pinned snapshot in an isolated slug directory

Publishing copies the complete draft into the next immutable version and clears the draft. It never mutates an older version or moves existing Agent and Template pins automatically.

Use the right Skill scope

Scope	Owner	Visible to	Management authority
Platform	Agent Barn platform	Every eligible Organization and Agent	Platform Administrators
Organization	One Organization	That Organization and its Agents	Users with skill.manage
Agent	One Agent	Only that Agent within its Organization	Users with required Agent Access permission

An Agent can use:
Platform Skills
+ its Organization’s Skills
+ its own Agent-private Skills

Another Agent’s private Skills are never visible or assignable. Platform Skills are global resources and do not belong to a customer Organization.

Package an immutable file snapshot

Every published Skill Version has exactly one root SKILL.md, optional supporting files in relative subpaths, and a complete snapshot of its own.

aai-example/
├── SKILL.md
└── references/
    ├── authentication.md
    └── commands.md

SKILL.md is always the entry point, and paths are relative to the Skill root.
Absolute paths, path traversal, unsafe segments, archive metadata, and paths differing only by case are rejected.
ZIP data may be accepted as migration input, but ZIP bytes are not the steady-state storage model.

./skills/<skill-root>/SKILL.md

./skills/aai-github/SKILL.md
./skills/aai-jira/SKILL.md
./skills/aai-bitbucket/SKILL.md

Create and publish a Skill

Create the lineage in its Platform, Organization, or Agent scope.
Agent Barn creates its initial unpublished draft.
Add or edit draft files, metadata, and provider requirements.
Save the draft without affecting published consumers.
Publish it to create the next immutable version and clear the draft.

Renaming an owned Skill updates lineage-level display metadata. Content, description, provider requirements, and file changes are draft-gated. Starting a draft for a published Skill seeds it from the latest published version; discarding leaves published versions unchanged.

Keep identity and mount paths stable

The immutable slug is the Skill’s root directory. Renaming a Skill does not change its slug, mount directory, or SKILL.md pointer.

Hermes:   /workspace/skills
OpenClaw: /home/node/.openclaw/workspace/skills

Agent Barn materializes each exact pinned version under its isolated slug directory and adds it to the generated manifest. Path collisions are reported instead of silently overwriting files.

Assign an exact published version

An Agent assignment records:

Skill lineage + pinned version

A caller can select an exact published version.
If omitted, Agent Barn pins the latest published version available at that moment.
Publishing later does not update the Agent; explicitly repin it to adopt another version.
A Skill with only an unpublished draft cannot be assigned as a published Skill.
Runtime start mounts the Agent’s pinned snapshot, not whichever version happens to be latest.

Use Agent Configuration to manage assignments and lifecycle actions.

Pin exact Skills in Templates and Overrides

Templates and Agent Template Overrides require an exact published Skill Version:

skill_id + skill_version

A Template Version’s Skill requirements are immutable snapshots. Publishing a new Skill Version does not rewrite existing Template Versions or Agent pins; updating a Template or Agent requires explicit selection of compatible published versions.

Standalone requirements: every listed Skill must be assigned.
Requirement groups: at least one Skill in the group must be assigned.

Validate providers without handling credentials

A Skill can declare required providers as integration metadata. Agent configuration validates them against the Agent’s configured tool Integration Secrets.

Understand bundled Platform Skills

Bundled aai-cli Skills are Platform Skills. The checked-in bootstrap bundle uses isolated integration directories, each with one root SKILL.md and optional references. After bootstrap seeding, the database is canonical: seeding fills missing built-in lineages but does not continuously overwrite customer-owned Skills.

Built-in aai_cli lineages are protected from deletion. An Organization cannot edit a Platform Skill in place; it creates an Organization fork.

Fork and update a Skill source

A fork creates an independent lineage while recording its exact direct source:

source Skill ID + source Skill Version

Supported directions are Platform to Organization, Platform to Agent-private, and Organization to Agent-private. A fork starts with an unpublished draft, copies its source file tree, metadata, and provider requirements, and changes neither its source nor existing consumer pins. It becomes independently versioned after publishing.

Apply a source update

No draft: copy the newest direct-source snapshot and publish it immediately as the fork’s next immutable version.
Existing draft: replace the draft’s files and source-derived metadata with the newest direct-source snapshot, then leave it unpublished for review.

Apply Update is replacement-based, not a three-way merge. Existing Agents and Templates never repin automatically after a source update.

Review history and delete safely

Version history is listed newest first. Authorized users can inspect a version’s number, publication metadata, description, required providers, direct-source provenance, immutable file tree, and file contents. Historical snapshots remain read-only.

Delete a published version

Delete through the owning scope only when it is not the lineage’s last published version and no Agent pin, Template requirement, Agent Template Override requirement, draft source, or fork source references it. Deleting an unreferenced historical version does not affect Runtime mounts because Agents use exact pins.

Delete a custom lineage

An unused custom lineage can be permanently deleted by its owner. This removes its draft, published versions, version files, and lineage metadata; it is not an archive or automatic consumer cleanup. Deletion is blocked by Agent assignments (including soft-deleted Agent assignments), Template or Override requirements, and fork source provenance.

Use the matching management surface

The list, detail, draft, history, and file-browser patterns are shared across scopes. Management actions still depend on ownership and permission.

Platform

Platform Administrators manage global Skills.

/dashboard/platform/skills
/dashboard/platform/skills/new
/dashboard/platform/skills/{skill_id}

Organization

skill.read reads; skill.manage mutates shared definitions.

/dashboard/{org_id}/settings?tab=skills
/dashboard/{org_id}/settings/skills/new
/dashboard/{org_id}/settings/skills/{skill_id}

Agent-private

All operations are subordinate to the owning Agent’s authority.

/dashboard/{org_id}/agents/{agent_id}/configuration?section=skills
/dashboard/{org_id}/agents/{agent_id}/skills/new
/dashboard/{org_id}/agents/{agent_id}/skills/{skill_id}

API route patterns

Scope	Prefix
Platform	`/api/v1/platform/skills`
Organization	`/api/v1/organizations/{organization_id}/skills`
Agent-private	`/api/v1/organizations/{organization_id}/agents/{agent_id}/skills`

POST   /
PATCH  /{skill_id}
DELETE /{skill_id}

GET    /{skill_id}/files
GET    /{skill_id}/versions
GET    /{skill_id}/versions/{version}
DELETE /{skill_id}/versions/{version}

GET    /{skill_id}/draft
POST   /{skill_id}/draft
PATCH  /{skill_id}/draft
DELETE /{skill_id}/draft
POST   /{skill_id}/draft/publish

POST   /{skill_id}/fork
POST   /{skill_id}/source-update

Not every operation is valid for every visible Skill. Mutation depends on the route’s scope, ownership, source type, and caller authority.

Troubleshooting

My Agent cannot use a Skill

Scope, publication, or pin

Confirm it is visible in the Agent’s Platform, Organization, or private scope, has a published version, and has an explicit compatible pin. A draft alone is not assignable.

A provider-required Skill cannot be assigned

Integration validation

Configure the required tool Integration Secret on the Agent. Do not put provider or Communication Connection credentials in the Skill.

A source update overwrote my draft

Expected replacement behavior

Apply Update replaces a current draft with the direct-source snapshot and does not merge local changes. Preserve intended local changes before applying it.

A version or lineage cannot be deleted

Reference protection

Review Agent pins, Template and Override requirements, draft sources, fork provenance, and soft-deleted Agent assignments.

A file does not mount

Path validation or collision

Check for an absent root SKILL.md, unsafe or case-colliding paths, then inspect startup output. Materialization reports collisions instead of silently overwriting files.

Recommended practices

Keep each Skill focused, versioned, and isolated in its own root directory.
Publish intentionally, then explicitly repin controlled Agent and Template rollouts.
Use forks for customization and review source updates before publication.
Keep credentials, provider payloads, and Communication Connection configuration out of Skill files.