--- title: Work with Skills canonical: "https://agentbarn.dev/guides/templates-and-skills/skills" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-02T11:46:37.000Z" author: Agent Barn description: "Learn how Agent Barn Skills use immutable file snapshots, exact Agent and Template version pins, scope-aware ownership, source updates, and Runtime materialization." tags: [Templates and Skills, Concept, "Skill authors, Agent operators, Organization administrators, and Agent editors", Skills, Custom Skill, Platform Skill, Agent-private Skill, Skill files, SKILL.md, Skill Version, Skill assignment, required providers, fork Skill, Skill draft, workspace mounting] categories: [Guides, Templates and Skills] --- - 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. **The Skill contract** A Skill is not one mutable Markdown document. It has a stable lineage, at most one mutable draft, and zero or more immutable published versions. A new lineage starts with a draft and no published version; its first publish creates version `1`. ## 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.md ./skills/aai-github/SKILL.md ./skills/aai-jira/SKILL.md ./skills/aai-bitbucket/SKILL.md ``` ## Create and publish a Skill 1. Create the lineage in its Platform, Organization, or Agent scope. 2. Agent Barn creates its initial unpublished draft. 3. Add or edit draft files, metadata, and provider requirements. 4. Save the draft without affecting published consumers. 5. 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](/guides/agents/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. **Skills do not provide access** Skills do not grant permissions, create provider accounts or Secrets, reveal credentials, install Communication Connections, or supply authentication automatically. Communication Connection credentials have their own encrypted lifecycle and are never supplied by a Skill. ## 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. ## Next steps - [Manage Skill Versions](/guides/templates-and-skills/skill-versions) - [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) - [Explore integrations](/guides/integrations) and [manage credentials](/guides/integrations/credentials)