Loading every instruction, checklist, and script into an agent’s context wastes space. Progressive disclosure keeps capabilities discoverable while loading detail only when it becomes relevant. section 3.3.6
A skill can load in three levels:
- Load frontmatter first: roughly 80 tokens per skill, carrying its name and description across requests. Make the description specific enough to match likely user requests. section 3.3.6
- Load the Markdown instructions when the skill matches a request or is invoked by name. Bodies typically run 1,000–3,000 tokens. section 3.3.6
- Keep referenced files as paths until needed; load checklists, templates, or scripts only when the procedure reaches them. section 3.3.6
pull-request-review/ ├── SKILL.md # frontmatter + instructions ├── references/ # the full review checklist ├── scripts/ # run-lint.sh, check-migrations.sh └── assets/ # PR description template
A skill directory separates its instructions from reference material, scripts, and assets. section 3.3.6

