Skip to main content

Writing a Skill

Skills are reusable instructions that agents invoke during Heartbeats — markdown files that teach agents how to perform specific tasks.

Prerequisites​

Skill Structure​

A skill is a directory containing a SKILL.md file, with optional supporting files in a references/ subfolder:

skills/
└── my-skill/
    ├── SKILL.md
    └── references/
        └── examples.md

SKILL.md Format​

---
name: my-skill
description: >
  Short description of what this skill does and when to use it.
  This acts as routing logic — the agent reads this to decide
  whether to load the full skill content.
---

# My Skill

Detailed instructions for the agent...

Frontmatter Fields​

FieldRequiredDescription
nameYesUnique kebab-case identifier for the skill
descriptionYesRouting description — tells the agent when to use this skill

Write the description as decision logic, not marketing copy. Include "use when" and "don't use when" guidance so the agent knows whether to load it.

How Skills Work at Runtime​

  1. The agent sees skill metadata (name and description) in its context.
  2. The agent decides whether the skill is relevant to its current task.
  3. If relevant, the agent loads the full SKILL.md content.
  4. The agent follows the instructions in the skill.

This keeps the base prompt small — full skill content loads on demand only.

End-to-End Example​

Here is a minimal skill that teaches an agent to write API endpoint documentation:

---
name: document-api-endpoint
description: >
  Use when asked to document an API endpoint. Produces a consistent
  reference entry with method, path, params table, request example,
  and response example. Don't use for conceptual overviews or how-tos.
---

# Document API Endpoint

## Steps

1. Identify the HTTP method, path, and auth requirements.
2. List all path, query, and body parameters in a table: Name · Type · Required · Description.
3. Write one request example using a realistic payload.
4. Write one response example for the success case and one for the main error case.
5. Link to any related endpoints.

Best Practices​

  • Write descriptions as routing logic. Include explicit "use when" / "don't use when" guidance.
  • Be specific and actionable. Agents should be able to follow skills without ambiguity.
  • Include code examples. Concrete API calls and commands are more reliable than prose.
  • Keep skills focused. One skill per concern; don't combine unrelated procedures.
  • Use references/ for depth. Put supporting detail in references/ rather than bloating the main SKILL.md.

Skill Injection​

Adapters make skills discoverable to their agent runtime. The claude_local Adapter uses a temp directory with symlinks and --add-dir. The codex_local Adapter uses the global skills directory. See Creating an Adapter for details.

Verification​

Confirm the skill parses and registers before relying on it:

  1. Import it into a squad from its directory:

    slaw skills import ./skills/my-skill --squad-id <SQUAD_ID>

    A malformed SKILL.md (missing name or description) is rejected here — a clean import means the frontmatter is valid.

  2. Inspect the registered skill to confirm its metadata resolved as expected:

    slaw skills inspect my-skill --squad-id <SQUAD_ID>

    The name and description should match your frontmatter. Once a relevant agent next wakes, the skill's metadata appears in its context and it loads the full SKILL.md on demand.

Next steps​