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
11# prettier-ignore
12description: "Use when reviewing for X, checking Y, or verifying Z - include all semantic triggers"
13model: opus
14---
15```
16 
17**Critical constraints:**
18 
19- **Single line only** - Claude Code doesn't parse block scalars (`>` or `|`) correctly
20- **Use `# prettier-ignore`** - Add before description to allow longer, richer triggers
21- **Use quotes** - Always quote descriptions to handle special characters like colons
22 
23## Description Philosophy
24 
25Agents are LLM-triggered. Descriptions should match against **user requests** to enable
26Claude Code to auto-select the right agent. Use "Use when..." format with rich semantic
27triggers.
28 
29**Do: Match user language**
30 
31Think about what users will say:
32 
33- "review the code"
34- "check if this is production ready"
35- "debug this error"
36- "test in the browser"
37 
38Include those exact phrases in your descriptions.
39 
40**Do: Include variations**
41 
42```yaml
43# prettier-ignore
44description: "Use when reviewing for production readiness, fragile code, error handling, resilience, reliability, or catching bugs before deployment"
45```
46 
47This triggers on: "review for production", "check fragile code", "error handling
48review", "catch bugs", etc.
49 
50**Don't: Describe what it does**
51 
52Bad: `"A code reviewer that analyzes production readiness and error handling patterns"`
53 
54This is technical documentation, not a semantic trigger.
55 
56## Example Agent
57 
58```yaml
59---
60name: test-runner
61# prettier-ignore
62description: "Use when running tests, checking test results, or verifying tests pass before committing"
63model: haiku
64---
65I run tests using the specified test runner (bun, pnpm, pytest, etc) and return a terse
66summary with pass count and failure details only. This preserves your context by
67filtering verbose test output to just what's needed for fixes.
68 
69[Rest of agent prompt...]
70```
71 
72## Reviewer Agent Structure
73 
74Reviewer agents (agents that analyze code and report findings) should include two
75additional sections:
76 
77### Review Signals
78 
79Replace prose "What I Look For" sections with scannable bullet lists. These prime the
80LLM to pattern-match against specific signals.
81 
82```markdown
83## Review Signals
84 
85These patterns warrant investigation:
86 
87**Category name**
88 
89- Specific pattern to look for
90- Another specific pattern
91- Concrete example of the smell
92 
93**Another category**
94 
95- Pattern
96- Pattern
97```
98 
99Bullet structure primes the LLM to look for these specific signals. Each bullet becomes
100a micro-prompt. Not exhaustive—representative signals that train attention in the right
101direction.
102 
103### Handoff
104 
105Reviewer agents typically run as subagents called by an orchestrator (like
106multi-review). Add context so the agent understands its output goes to another LLM, not
107a human.
108 
109```markdown
110## Handoff
111 
112You're a subagent reporting to an orchestrating LLM (typically multi-review). The
113orchestrator will synthesize findings from multiple parallel reviewers, deduplicate
114across agents, and decide what to fix immediately vs. decline vs. defer.
115 
116Optimize your output for that receiver. It needs to act on your findings, not read a
117report.
118```
119 
120Do NOT prescribe output format in the Handoff section. Given context about who receives
121the output and what they'll do with it, the agent can determine the most effective
122format itself. Avoid over-specification.
123