schemas

# Frontmatter Schemas

## Agent Frontmatter

```yaml
---
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`

---