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
11description: "Keep under 75 characters"
12---
13```
14 
15**Critical constraints:**
16 
17- **Single line only** - Claude Code doesn't parse block scalars (`>` or `|`) correctly
18- **Under 75 characters** - With `description: ` prefix (13 chars), total line must be
19  under 88 to prevent prettier wrapping
20- **Use quotes** - Always quote descriptions to handle special characters like colons
21 
22**Valid formats:**
23 
24- `description: "Double quoted under 75 chars"` (recommended)
25- `description: 'Single quoted under 75 chars'`
26- `description: Plain text under 75 chars` (only if no special characters)
27 
28## Writing Concise Descriptions
29 
30Keep descriptions focused on WHEN to use the skill:
31 
32- Good: "Use when rough ideas need design before code"
33- Too long: "Use when developing rough ideas into designs before writing code. Refines
34  concepts through collaborative questioning..."
35 
36If you need to cut content to stay under 75 chars, move that detail into the skill body
37instead.
38 
39## Example Skill
40 
41```yaml
42---
43name: systematic-debugging
44description: "Use for bugs, test failures, or unexpected behavior needing root cause"
45---
46 
47<objective>
48Find the root cause before writing fixes. Understanding why something breaks leads to
49correct fixes. Guessing wastes time and creates new problems.
50 
51Core principle: If you can't explain WHY it's broken, you're not ready to fix it.
52</objective>
53 
54[Rest of skill content...]
55```
56