CLAUDE.md

1# Creating Claude Code Agents
2 
3When creating custom agent files in `.claude/agents/`, the YAML frontmatter format
4matters.
5 
6## Valid Frontmatter Format
7 
8```yaml
9---
10name: agent-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 invoke the agent:
31 
32- Good: "Invoke for design review"
33- Too long: "Invoke for design review with Playwright testing checking WCAG
34  compliance..."
35 
36If you need to cut content to stay under 75 chars, move that detail into the agent body
37instead.
38 
39## Example Agent
40 
41```yaml
42---
43name: test-runner
44description: "Invoke to run tests with terse results"
45---
46I run tests using the specified test runner (bun, pnpm, pytest, etc) and return a terse
47summary with pass count and failure details only. This preserves your context by
48filtering verbose test output to just what's needed for fixes.
49 
50[Rest of agent prompt...]
51```
52