Frontmatter Schemas
Agent Frontmatter
---
name: agent-name # Required: lowercase-with-hyphens
description: | # Required: detailed with examples
Use this agent when [scenario]. Examples:
(1) "Task description" - launches agent for X
(2) "Task description" - launches agent for Y
(3) "Task description" - launches agent for Z
model: sonnet # Required: sonnet | opus | haiku
color: purple # Optional: purple | cyan | green | orange | blue | red
tools: TodoWrite, Read, Write # Required: comma-separated, space after comma
skills: skill1, skill2 # Optional: referenced skills
---
Field Reference
| Field |
Required |
Values |
Description |
name |
Yes |
lowercase-with-hyphens |
Agent identifier |
description |
Yes |
Multi-line string |
3-5 usage examples |
model |
Yes |
sonnet, opus, haiku |
AI model to use |
color |
No |
See colors below |
Terminal color |
tools |
Yes |
Tool list |
Available tools |
skills |
No |
Skill list |
Referenced skills |
Color Guidelines
| Color |
Agent Type |
Examples |
purple |
Planning |
architect, api-architect |
green |
Implementation |
developer, ui-developer |
cyan |
Review |
reviewer, designer |
orange |
Testing |
test-architect, tester |
blue |
Utility |
cleaner, api-analyst |
red |
Critical/Security |
(rarely used) |
Tool Patterns by Agent Type
Orchestrators (Commands):
- Must have:
Task, TodoWrite, Read, Bash
- Often:
AskUserQuestion, Glob, Grep
- Never:
Write, Edit
Planners:
- Must have:
TodoWrite, Read, Write (for docs)
- Often:
Glob, Grep, Bash
Implementers:
- Must have:
TodoWrite, Read, Write, Edit
- Often:
Bash, Glob, Grep
Reviewers:
- Must have:
TodoWrite, Read
- Often:
Glob, Grep, Bash
- Never:
Write, Edit
Command Frontmatter
---
description: | # Required: workflow description
Full description of what this command does.
Workflow: PHASE 1 → PHASE 2 → PHASE 3
allowed-tools: Task, Bash # Required: comma-separated
skills: skill1, skill2 # Optional: referenced skills
---
Field Reference
| Field |
Required |
Values |
Description |
description |
Yes |
Multi-line |
Command purpose and workflow |
allowed-tools |
Yes |
Tool list |
Tools command can use |
skills |
No |
Skill list |
Referenced skills |
Validation Checklist
Agent Frontmatter
Command Frontmatter
Common Errors
Invalid YAML Syntax
# WRONG - missing colon
name agent-name
# CORRECT
name: agent-name
Incorrect Tool Format
# WRONG - no spaces after commas
tools: TodoWrite,Read,Write
# CORRECT
tools: TodoWrite, Read, Write
Missing Examples
# WRONG - too generic
description: Use this agent for development tasks.
# CORRECT
description: |
Use this agent when implementing TypeScript features. Examples:
(1) "Create a user service" - implements service with full CRUD
(2) "Add validation" - adds Zod schemas to endpoints
(3) "Fix type errors" - resolves TypeScript compilation issues
1---2name: schemas3description: YAML frontmatter schemas for Claude Code agents and commands. Use when creating or validating agent/command files.4---5
6# Frontmatter Schemas
7
8## Agent Frontmatter
9
10```yaml
11---
12name: agent-name # Required: lowercase-with-hyphens
13description: | # Required: detailed with examples
14 Use this agent when [scenario]. Examples:
15 (1) "Task description" - launches agent for X
16 (2) "Task description" - launches agent for Y
17 (3) "Task description" - launches agent for Z
18model: sonnet # Required: sonnet | opus | haiku
19color: purple # Optional: purple | cyan | green | orange | blue | red
20tools: TodoWrite, Read, Write # Required: comma-separated, space after comma
21skills: skill1, skill2 # Optional: referenced skills
22---
23```
24
25### Field Reference
26
27| Field | Required | Values | Description |
28|-------|----------|--------|-------------|
29| `name` | Yes | `lowercase-with-hyphens` | Agent identifier |
30| `description` | Yes | Multi-line string | 3-5 usage examples |
31| `model` | Yes | `sonnet`, `opus`, `haiku` | AI model to use |
32| `color` | No | See colors below | Terminal color |
33| `tools` | Yes | Tool list | Available tools |
34| `skills` | No | Skill list | Referenced skills |
35
36### Color Guidelines
37
38| Color | Agent Type | Examples |
39|-------|------------|----------|
40| `purple` | Planning | architect, api-architect |
41| `green` | Implementation | developer, ui-developer |
42| `cyan` | Review | reviewer, designer |
43| `orange` | Testing | test-architect, tester |
44| `blue` | Utility | cleaner, api-analyst |
45| `red` | Critical/Security | (rarely used) |
46
47### Tool Patterns by Agent Type
48
49**Orchestrators (Commands):**
50- Must have: `Task`, `TodoWrite`, `Read`, `Bash`
51- Often: `AskUserQuestion`, `Glob`, `Grep`
52- Never: `Write`, `Edit`
53
54**Planners:**
55- Must have: `TodoWrite`, `Read`, `Write` (for docs)
56- Often: `Glob`, `Grep`, `Bash`
57
58**Implementers:**
59- Must have: `TodoWrite`, `Read`, `Write`, `Edit`
60- Often: `Bash`, `Glob`, `Grep`
61
62**Reviewers:**
63- Must have: `TodoWrite`, `Read`
64- Often: `Glob`, `Grep`, `Bash`
65- Never: `Write`, `Edit`
66
67---
68
69## Command Frontmatter
70
71```yaml
72---
73description: | # Required: workflow description
74 Full description of what this command does.
75 Workflow: PHASE 1 → PHASE 2 → PHASE 3
76allowed-tools: Task, Bash # Required: comma-separated
77skills: skill1, skill2 # Optional: referenced skills
78---
79```
80
81### Field Reference
82
83| Field | Required | Values | Description |
84|-------|----------|--------|-------------|
85| `description` | Yes | Multi-line | Command purpose and workflow |
86| `allowed-tools` | Yes | Tool list | Tools command can use |
87| `skills` | No | Skill list | Referenced skills |
88
89---
90
91## Validation Checklist
92
93### Agent Frontmatter
94- [ ] Opening `---` present
95- [ ] `name` is lowercase-with-hyphens
96- [ ] `description` includes 3+ examples
97- [ ] `model` is valid (sonnet/opus/haiku)
98- [ ] `tools` is comma-separated with spaces
99- [ ] Closing `---` present
100- [ ] No YAML syntax errors
101
102### Command Frontmatter
103- [ ] Opening `---` present
104- [ ] `description` explains workflow
105- [ ] `allowed-tools` includes Task for orchestrators
106- [ ] Closing `---` present
107- [ ] No YAML syntax errors
108
109---
110
111## Common Errors
112
113### Invalid YAML Syntax
114```yaml
115# WRONG - missing colon
116name agent-name
117
118# CORRECT
119name: agent-name
120```
121
122### Incorrect Tool Format
123```yaml
124# WRONG - no spaces after commas
125tools: TodoWrite,Read,Write
126
127# CORRECT
128tools: TodoWrite, Read, Write
129```
130
131### Missing Examples
132```yaml
133# WRONG - too generic
134description: Use this agent for development tasks.
135
136# CORRECT
137description: |
138 Use this agent when implementing TypeScript features. Examples:
139 (1) "Create a user service" - implements service with full CRUD
140 (2) "Add validation" - adds Zod schemas to endpoints
141 (3) "Fix type errors" - resolves TypeScript compilation issues
142```
majiayu000