3.5 Skills system: SKILL.md, disclosure, bundling

SKILL.md structure

.claude/skills/
└── migration-audit/
    ├── SKILL.md
    ├── checklist.md
    └── examples/
        ├── unsafe-drop.sql
        └── safe-migration.sql

The manifest:

---
name: migration-audit
description: >
  Audit a pending SQL migration for safety issues. Consult
  `checklist.md` for the categories to check, and the files in
  `examples/` when you need to compare against known-good shapes.
argument-hint: (optional) path to the migration file
---

# Migration audit

Follow the categories in `checklist.md`. For each category, produce
a finding with severity: blocking, worth-fixing, or ok. Attach a
one-sentence justification per finding.

Do not modify the migration file. Report only.

Three properties matter:

• name / description — how the skill is discovered and invoked.
• The body — the top-level system prompt when the skill runs.
• The bundled files — supporting resources the body can point Claude at, without paying their token cost up front.

Progressive disclosure

The whole point of the bundled-files pattern is progressive disclosure: the skill body is short — a few hundred tokens — and only when the task actually calls for it does Claude open the checklist, the examples, the reference SQL.

Without this pattern, either:

• Your skill body is huge and eats context on every invocation, or
• Your skill body is short and misses cases the reference material would have caught.

With progressive disclosure, small skills stay small; big skills stay big only when they need to.

Bundling supporting files

Anything in the skill’s directory is available to Claude when the skill runs. Reference them by path in the body:

For each category, compare against `examples/safe-migration.sql`.
If the migration under review deviates significantly, flag it.

Claude will Read the referenced file when it needs to. This scales — a skill can carry 20 example files and a 500-line checklist without inflating every invocation.

Invocation

/migration-audit
/migration-audit migrations/20260214_add_email.sql

Same shape as slash commands. Skills that take arguments should specify argument-hint in the frontmatter so /help shows the shape.

When to use a skill vs a slash command vs a subagent

• Slash command — a repeated prompt shape, no attached files, no fresh context needed.
• Skill — a repeated shape with reference material that benefits from progressive disclosure.
• Subagent — a fresh isolated instance, especially when the work is broad and would clutter the main context.

The three compose: a skill can spawn a subagent; a slash command can invoke a skill.

Check your understanding

Quick check

—

You have a skill whose full reference material is ~500 lines. On most invocations, only a small part is needed. What is the right structure?

1. APaste the full 500 lines into the SKILL.md body so Claude always has it.
2. BKeep SKILL.md short (~few hundred tokens) with rules Claude needs every time; put the 500 lines in bundled files (`reference.md`, `examples/`) and have the body point Claude at them when needed.
3. CDo not use a skill; skills cannot handle that much material.
4. DSplit into ten separate skills.

Check answer→