CLAUDE.md

1# Creating Claude Code Skills
2 
3When creating custom skill files in `.claude/skills/`, the YAML frontmatter format
4matters.
5 
6## Valid Frontmatter Format
7 
8```yaml
9---
10name: skill-name
11# prettier-ignore
12description: "Use when X, Y, or Z - include all semantic triggers that should activate this skill"
13version: 1.0.0
14category: debugging
15triggers:
16  - "natural language phrase"
17  - "another trigger"
18---
19```
20 
21## Field Requirements
22 
23**name**: Letters, numbers, hyphens only. Use kebab-case (e.g., `systematic-debugging`).
24 
25**description**: Start with "Use when..." and include rich semantic triggers. Use
26`# prettier-ignore` to allow longer descriptions. Focus on triggering conditions, not
27process details.
28 
29- Good:
30  `"Use when debugging test failures, unexpected behavior, or needing root cause analysis"`
31- Bad: `"Finds root causes by tracing data flow and testing hypotheses"`
32 
33The "Description Trap": If your description contains process details, Claude follows the
34short description instead of reading the full skill content.
35 
36**version**: Semantic versioning. Bump when updating the skill.
37 
38**category**: Grouping for discovery. Common categories:
39 
40- `planning` - Design, architecture, brainstorming
41- `debugging` - Error investigation, root cause analysis
42- `research` - Web lookups, documentation review
43- `testing` - Test writing, coverage analysis
44- `meta` - Skills about skills, configuration
45 
46**triggers**: Natural language phrases that activate this skill. Include:
47 
48- Keywords users naturally say ("debug", "brainstorm", "research")
49- Questions ("why is this", "is this still")
50- Symptoms ("not working", "test failing")
51- Tool names ("youtube", "SKILL.md")
52 
53## Example Skill
54 
55```yaml
56---
57name: systematic-debugging
58# prettier-ignore
59description: "Use when debugging bugs, test failures, unexpected behavior, or needing root cause analysis before fixing"
60version: 1.1.0
61category: debugging
62triggers:
63  - "debug"
64  - "investigate"
65  - "root cause"
66  - "why is this"
67  - "not working"
68  - "test failing"
69---
70 
71<objective>
72Find the root cause before writing fixes. Understanding why something breaks leads to
73correct fixes.
74 
75Core principle: If you can't explain WHY it's broken, you're not ready to fix it.
76</objective>
77 
78[Rest of skill content...]
79```
80 
81## Composition Fields (Optional)
82 
83These fields let skills declare their place in a workflow. The Claude Code harness
84ignores them; the LLM reads and acts on them as part of the skill content.
85 
86**`next-skill`**: The skill or command to offer as a handoff after this one completes.
87Use the bare name (same as the slash command without `/`). The LLM surfaces this as a
88suggestion — the user confirms before the next skill runs. Never auto-invoke silently.
89 
90```yaml
91next-skill: ship
92```
93 
94**`requires`**: Prerequisites, as a YAML sequence of `skill:name`, `tool:name`, or
95`mcp:name` entries. Note: `next-skill` can target both skills and commands; commands
96(`.claude/commands/*.md`) don't have SKILL.md files and can't declare `requires` back.
97 
98```yaml
99requires:
100  - skill:brainstorming
101  - tool:Bash
102```
103 
104**`model-hint`**: Preferred model tier when this skill runs as a delegated subagent.
105Options: `sonnet`, `opus`, `haiku`.
106 
107```yaml
108model-hint: opus
109```
110 
111**`stability`**: Maturity marker — `stable` (default) or `experimental`. Omit for stable
112skills. Mark `experimental` when behavior may change or the skill is under active
113development.
114 
115```yaml
116stability: experimental
117```
118 
119## Critical Constraints
120 
121- **Single line descriptions** - Claude Code doesn't parse block scalars (`>` or `|`)
122- **Use `# prettier-ignore`** - Add before description to allow longer, richer triggers
123- **Use quotes** - Always quote descriptions to handle special characters
124- **Trigger-focused descriptions** - Focus on when to activate, not what it does
125