How skills work

# Skills

A skill is a folder of instructions the agent loads *only when the work
matches*. That is the whole point: it keeps specialised procedure out of
your main context until it is relevant.

## Format

Claude Code loads any `SKILL.md` under `.claude/skills/<name>/`:

```markdown
---
name: schema-change
description: Use when adding, altering or dropping a database column or table.
---

<the procedure>
```

The `description` is the only part that is always in context. It is what the
model matches against, so write it as a **trigger condition**, not a summary.

    Bad:  "Database migration best practices"
    Good: "Use when adding, altering or dropping a database column or table."

## Porting to other tools

| Tool | Where it goes |
|---|---|
| Claude Code | `.claude/skills/<name>/SKILL.md` — loaded on match |
| Codex / AGENTS.md | Paste the body into AGENTS.md under a heading, or keep as `docs/procedures/<name>.md` and reference it |
| Cursor | `.cursor/rules/<name>.mdc` with a `description` and `globs` frontmatter |
| Cline / Roo Code | A custom mode, or a file in the workspace you reference by name |

For the tools without automatic matching, the fallback that works: keep the
files in `docs/procedures/` and add one line to your memory file —
*before doing X, read docs/procedures/x.md.*

## When to add one

**After the third time.** If you have talked the agent through the same
procedure three times, write it down. Adding skills speculatively costs
context and gets stale.

## When a skill is the wrong tool

- The procedure applies to *every* task → memory file, not a skill.
- You want it to run on demand by name → slash command, not a skill.
- It is a hard constraint that must never be violated → permissions or a
  hook. Instructions are advice; hooks are enforcement.