Work with Skills

Before you begin

Depending on the action, you need:

• skill.read permission to view Skills and their published versions
• skill.manage permission to create, edit, publish, fork, or delete Custom Skill versions
• Access to an Agent to view its assigned Skills
• agent.update permission to add, remove, or repin an Agent’s Skills
• Required provider credentials for Skills that integrate with external services

How Skills work

A Skill has a stable lineage and one or more published versions.

1. Skill lineage
2. Published version
3. Agent pin
4. Mounted workspace files

Skill lineage
Incident Triage
ID: 6fd2f967-0d12-477a-8af1-a90dbfca87a3
        │
        ├── v1
        ├── v2
        └── v3 · latest
              │
              ├── Agent A pins v3
              └── Agent B pins v2

Each published version contains a complete immutable file snapshot. An Agent assignment references the Skill lineage and an exact published version.

What a Skill provides

A Skill can contain:

• Usage instructions
• Tool-specific workflows
• Domain terminology
• Reference material
• Troubleshooting procedures
• Examples and conventions
• Links or pointers to available tools
• Guidance for working with an external provider

A Skill does not store the Agent’s provider credentials. Credentials remain in the Agent’s Secrets and integration configuration.

Built-in and Custom Skills

Understand the Skill file structure

Every Custom Skill must include a SKILL.md entry point. A small Skill might look like this:

incident-triage/
├── SKILL.md          entry point
├── references/
│   ├── severity-levels.md
│   └── escalation-policy.md
└── examples/
    └── sample-incident.md

Directories are implied by file paths. Agent Barn stores a flat collection of relative paths and file contents, rather than separate directory records.

Example SKILL.md

# Incident triage

Use this Skill when an incoming report may describe a production incident.

## Workflow

1. Confirm the affected service and environment.
2. Determine the severity using `references/severity-levels.md`.
3. Collect timestamps, request IDs, and recent changes.
4. Follow `references/escalation-policy.md` when escalation is required.
5. Record the investigation outcome.

## Safety

- Do not claim that an incident is resolved without verification.
- Do not expose credentials or private customer information.
- Escalate when the severity is unclear.

Keep SKILL.md focused on when and how the Agent should use the Skill. Put longer reference material in separate files.

Skill identity and mount paths

When a Custom Skill is created, Agent Barn generates a slug from its name.

Name:     Incident Triage
Slug:     incident-triage
Root:     incident-triage
Entry:    SKILL.md
Mount:    ./skills/incident-triage/SKILL.md

The slug and root directory remain stable. Renaming the Skill changes its display name but does not move its files:

Original name: Incident Triage
New name:      Production Incident Triage

Mount remains:
./skills/incident-triage/SKILL.md

This prevents existing file references from breaking after a rename.

If another Custom Skill already uses the generated slug, Agent Barn adds a numeric suffix such as incident-triage-2.

Write effective Skill content

A useful Skill should answer four questions:

1. When should the Agent use it?
2. What information does the Agent need?
3. What sequence should the Agent follow?
4. What constraints or safety rules apply?

A recommended structure is:

# Skill name

A short explanation of the Skill.

## When to use

- Use it when...
- Do not use it when...

## Inputs

- Information or access the Agent needs

## Workflow

1. First action
2. Verification
3. Final action

## Safety

- Actions the Agent must not take
- Conditions that require escalation

## References

- `references/example.md`

Use direct instructions and observable completion criteria. Avoid relying on unstated organizational knowledge.

Add supporting files

Supporting files can hold material that would make SKILL.md too long, such as policies, runbooks, field definitions, query examples, output templates, troubleshooting matrices, and provider-specific notes.

Reference supporting files using paths relative to the Skill root:

Review `references/escalation-policy.md` before escalating an incident.

Do not include the root directory in an internal relative reference, unless the tool consuming the file specifically requires it.

File requirements

Paths must:

• Be relative
• Use forward slashes
• Name a file rather than a directory
• Avoid . and .. path segments
• Avoid absolute paths
• Avoid archive metadata such as __MACOSX
• Use letters, digits, dots, dashes, and underscores in each segment
• Be unique without relying on letter case

These paths conflict, because Agent Barn treats paths as case-insensitive during validation:

references/Policy.md
references/policy.md

Configure required providers

A Skill can declare external providers that must be configured before the Skill is assigned or used. Examples include GitHub, Jira, Confluence, Bitbucket, Google Workspace, Zoho Mail, Zoho Calendar, Slack, Pipedrive, and Firecrawl.

The relationship is:

1. Skill requires Jira The Skill declares its required providers
2. Agent must have a Jira credential Configured as an Agent Secret or platform integration
3. Skill can be assigned and mounted The runtime loads the pinned version at Agent start

Provider requirements do not contain credentials. They declare which Agent Secrets or platform integrations must exist. When adding a Skill to an Agent, Agent Barn can prompt for the required provider configuration.

Understand Template Skill requirements

Templates reference a Skill lineage, not one specific Skill version. The Agent still pins an exact version when that Skill is assigned.

Template requires:
Incident Triage Skill lineage

Agent A assignment:
Incident Triage v2

Agent B assignment:
Incident Triage v4

Both Agents satisfy the Template requirement, because both explicitly assign the required lineage.

Template requirements can be:

• Standalone: every listed Skill must be assigned
• Grouped: at least one Skill in the group must be assigned

A Template requirement does not silently assign the Skill. The Agent must have an explicit assignment.

Built-in provider Skills and implicit mounting

At startup, Agent Barn may mount eligible built-in provider Skills when the matching provider credential exists.

This implicit mount:

• Uses the appropriate built-in aai-cli content
• Does not create an explicit Agent Skill assignment
• Does not replace explicit Template requirement validation
• Does not create a visible version pin in the Agent’s assignments

When a Template explicitly requires a Skill, assign that Skill to the Agent rather than relying on implicit mounting.

Built-in Skill forks do not track updates

A Skill fork is a one-time snapshot.

Built-in Jira Skill v3
        │
        └── Fork
            Custom Jira Skill v1
                    │
                    ├── Custom v2
                    └── Custom v3

Built-in Jira Skill v4
        │
        └── No automatic update relationship

Future Built-in Skill changes are not copied into the Custom Skill, and do not produce an update badge. Compare newer Built-in content manually, and publish the desired changes into the Custom Skill.

Runtime mounting

At Agent start, assigned Skills are mounted under ./skills/{root_dir}/.

A Custom Skill normally mounts under its immutable slug:

./skills/incident-triage/SKILL.md

Built-in provider Skills deliberately share the aai-cli root:

./skills/aai-cli/jira_skill.md
./skills/aai-cli/github_skill.md

Agent Barn adds a pointer to each Skill’s entry file in the rendered tool context. For a Custom Skill, the pointer is derived from its current name, description, root directory, and entry path.

Handle workspace collisions

Two assigned Skills can claim the same workspace path. Agent Barn applies Skills in a stable name order:

1. The first Skill claims the path.
2. The later conflicting file is skipped.
3. The collision is recorded in the Agent’s startup logs.

Skill A claims:
./skills/shared/reference.md

Skill B also claims:
./skills/shared/reference.md

The first claim wins.

Custom Skills normally have separate root directories, so collisions are uncommon. They are more likely among Skills that intentionally share a root, or contain incompatible legacy paths.

API reference

Create a Skill

POST /api/v1/organizations/{organization_id}/skills
Content-Type: application/json

{
  "name": "Incident Triage",
  "description": "Guidance for investigating and escalating production incidents.",
  "required_providers": [
    "jira"
  ],
  "files": [
    {
      "path": "SKILL.md",
      "content": "# Incident triage\n\nUse this Skill for production incidents."
    },
    {
      "path": "references/severity-levels.md",
      "content": "# Severity levels\n\n## SEV-1\n\nCritical production outage."
    }
  ]
}

A successful request returns 201 Created and publishes version 1.

List Skills

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

Optional filters include search and source:

GET /api/v1/organizations/{organization_id}/skills?search=incident&source=custom&page=1&page_size=15

Read the latest published files

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

The response includes the Skill identity and source, the latest published version, the description, the root directory and entry path, required providers, the latest published files, whether the Skill is assigned to an Agent, and whether a draft exists.

Rename a Custom Skill

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

{
  "name": "Production Incident Triage"
}

Only the name can be changed directly. The slug, root directory, and entry path remain unchanged.

Fork a Built-in Skill

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

No request body is required. A successful request returns 201 Created with the new Custom Skill at version 1 and an open draft.

Start or retrieve a draft

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

This is a get-or-create operation. If a draft exists, Agent Barn returns it. Otherwise, it creates one from the latest published version.

Save a draft

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

{
  "description": "Updated incident investigation workflow.",
  "required_providers": [
    "jira"
  ],
  "files": [
    {
      "path": "SKILL.md",
      "content": "# Incident triage\n\nFollow the updated workflow."
    },
    {
      "path": "references/severity-levels.md",
      "content": "# Severity levels\n\n..."
    }
  ]
}

Publish or discard a draft

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

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

Publishing creates the next immutable version and clears the draft. Discarding clears the draft without changing the published version.

Troubleshooting

Recommended practices

• Give each Skill one clear responsibility
• Keep the entry-point instructions concise
• Put long reference material in supporting files
• Declare every required provider
• Use relative, stable file paths
• Avoid references that depend on the display name
• Test a Skill with a stopped non-production Agent
• Pin exact versions for controlled rollouts
• Review startup logs after changing assignments
• Use Organization Templates to standardize required Skills
• Fork Built-in Skills only when customization is necessary
• Treat a fork as independent after creation
• Publish a new version instead of mutating history

Next steps

Continue to Manage Skill versions to learn how drafts, immutable versions, Agent pins, rollback, and protected version deletion work.

• Work with templates
• Use Agent overrides
• Configure an Agent