3.0 KiB

Raw Blame History

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

---
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

3.0 KiB Raw Blame History