A skill's documentation is its description, instructions, and examples. Written for Claude (who reads it to decide invocation and behavior) and for humans (who maintain it and decide whether to use it).
This page covers what good skill documentation looks like.
The frontmatter description is the most-read piece. Brief; specific; matches the user's mental model of when this skill is needed.
description: Reviews code for adherence to project guidelines, style guides, and best practices. Use proactively after writing or modifying code.
Specific (code review); contextualized (after writing/modifying); proactive trigger (when to use without being asked).
The body of SKILL.md. Tells Claude what to do.
Structure:
Length: long enough to be specific; short enough to be applicable.
Real input/output examples. Usually the most-useful piece.
Example: User asks "review this PR"
Steps:
1. git diff main..HEAD
2. Identify changes
3. Apply review checklist
4. Report findings
Output:
- Style: 2 issues
- Logic: 1 issue
- ...
Concrete examples disambiguate better than abstract description.
Some skills should NOT be invoked in certain cases. Document these:
SKIP when:
- The user just wants to commit (no review needed)
- The change is trivial (one-line typo fix)
- The file is auto-generated
In addition to Claude-facing documentation, skills often need human docs:
How to install/enable the skill. Path; configuration; dependencies.
Brief explanation for users browsing skills.
When would I use this? Sample interactions.
What doesn't this skill handle? Where's it not the right tool?
Who maintains it; how to report issues; how to contribute.
The frontmatter description is the most-read piece. One or two sentences.
SKILL.md has the essentials. References folder has depth. Claude reads SKILL.md always; references when relevant.
my-skill/
├── SKILL.md (overview, key points)
└── references/
├── api-spec.md (read when API details needed)
└── examples.md (read for examples)
This keeps SKILL.md scannable.
"Use parameterized queries" beats "ensure security best practices."
Headings, bullet points, code blocks. Skim-friendly.
Examples that match real usage. Update when usage changes.
For skills shared widely:
---
name: my-skill
description: ...
version: 2.1.0
---
Helps users know if a behavior change is intentional.
"Powerful, intelligent, comprehensive..." Useless.
"Follow best practices." What practices?
"This skill is awesome." Tells nothing about behavior.
Code samples for an API that's changed. Misleading.
Page on what skills are; user wants to know what this specific skill does.
Make triggers explicit:
## When to use
USE when:
- User asks for [specific request]
- Code shows [specific pattern]
- Workflow includes [specific step]
DON'T USE when:
- [explicit exclusion]
- [another exclusion]
For multi-step skills:
## Workflow
1. **Identify scope**: what's being changed?
2. **Plan**: write design doc
3. **Implement**: TDD
4. **Verify**: tests pass; build succeeds
5. **Review**: invoke code-review skill
Each step has its own subsection if needed.
A "Common Failure Patterns" section. Helps Claude avoid known issues.
Multiple examples covering different scenarios:
## Examples
### Simple case
[example]
### Complex case
[example]
### Edge case: when X
[example]
Link to related skills:
## See Also
- `brainstorming` — invoke before this for new features
- `writing-plans` — invoke before implementation
- `requesting-code-review` — invoke after this
For organizations with many skills:
Central index of all skills. What each does; how to use.
Standardized format for SKILL.md across the organization. Consistency helps Claude apply them similarly.
Skill changes should be reviewed like code. Skills affect Claude's behavior; reviews catch issues.
Track changes. Especially important for skills used in production workflows.