# Skill Structure

The standard anatomy of a Claude Code skill, and how content is split across
it via progressive disclosure.

## Required

```
skills/<skill-name>/
└── SKILL.md
```

`SKILL.md` is routing-only: "when to use" plus pointers to `workflows/*.md`
and `references/*`. It should not inline substantial content — see
`${CLAUDE_PLUGIN_ROOT}/references/progressive-disclosure/splitting-knowledge.md`
for the size guidance that applies here too (SKILL.md itself should stay
<=50 lines).

## Frontmatter expectations

```yaml
---
name: skill-name
description: [Action verb] [what]. [Unambiguous trigger].
---
```

- `name` - kebab-case, <=64 chars, matches the directory name
- `description` - follows the formula in
  `${CLAUDE_PLUGIN_ROOT}/references/layout/descriptions.md`; this is the
  only field another model sees before deciding whether to open the skill,
  so the trigger must be unambiguous

## Common additions

```
skills/<skill-name>/
├── SKILL.md
├── workflows/
│   └── <workflow-name>.md   # one file per distinct task the skill handles
├── references/
│   └── <topic>/
│       ├── reference.md     # required routing file, see reference.md below
│       └── <knowledge-doc>.md
├── templates/                # repetitive structures to copy/fill
├── scripts/                  # mechanical, deterministic operations
└── state/                    # gitignored working data, if the skill needs it
```

- `workflows/` - one file per task the skill handles (e.g. "create X",
  "audit X"). Each workflow states inputs, subtasks with subagent-tier
  hints, and outputs.
- `references/` - knowledge organized by topic subdirectory. Every
  subdirectory needs a `reference.md` (see
  `${CLAUDE_PLUGIN_ROOT}/references/layout/reference.md`).
- `templates/` and `scripts/` are optional and only added when the skill
  has mechanical, repeatable work to offload from the model.

## Progressive disclosure

Splitting is not optional past a certain size — it's how the skill stays
navigable for a model that only reads what it needs:

- SKILL.md: routing only, <=50 lines
- `reference.md` files: <=50 lines, list what's here and when to read each
  file, never duplicate the child files' content
- Knowledge docs: target <=150 lines, hard limit ~200 (split if approaching)
- Directory depth: <=3 levels (`references/topic/subtopic/`)

Full splitting criteria (the "always needed together?" test, signs a doc
should split, how to split) live in
`${CLAUDE_PLUGIN_ROOT}/references/progressive-disclosure/splitting-knowledge.md`.

## Reversion protection (optional, added once a skill stabilizes)

- `invariants.md` at skill root - behaviors that must not change without
  explicit approval
- `examples/golden/` - golden examples that pin correct behavior
- `.decisions/` - dated decision records

See `${CLAUDE_PLUGIN_ROOT}/references/tool-patterns/reversion-protection.md`.

## Creating a new skill

Follow the cc-architect workflow:
→ `${CLAUDE_PLUGIN_ROOT}/workflows/create-skill.md`