87 lines
3.0 KiB
Markdown
87 lines
3.0 KiB
Markdown
|
# 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`
|