143 lines
3.8 KiB
Markdown
143 lines
3.8 KiB
Markdown
---
|
|
name: schemas
|
|
description: YAML frontmatter schemas for Claude Code agents and commands. Use when creating or validating agent/command files.
|
|
---
|
|
|
|
# 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`
|
|
|
|
---
|
|
|
|
## Command Frontmatter
|
|
|
|
```yaml
|
|
---
|
|
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
|
|
- [ ] Opening `---` present
|
|
- [ ] `name` is lowercase-with-hyphens
|
|
- [ ] `description` includes 3+ examples
|
|
- [ ] `model` is valid (sonnet/opus/haiku)
|
|
- [ ] `tools` is comma-separated with spaces
|
|
- [ ] Closing `---` present
|
|
- [ ] No YAML syntax errors
|
|
|
|
### Command Frontmatter
|
|
- [ ] Opening `---` present
|
|
- [ ] `description` explains workflow
|
|
- [ ] `allowed-tools` includes Task for orchestrators
|
|
- [ ] Closing `---` present
|
|
- [ ] No YAML syntax errors
|
|
|
|
---
|
|
|
|
## Common Errors
|
|
|
|
### Invalid YAML Syntax
|
|
```yaml
|
|
# WRONG - missing colon
|
|
name agent-name
|
|
|
|
# CORRECT
|
|
name: agent-name
|
|
```
|
|
|
|
### Incorrect Tool Format
|
|
```yaml
|
|
# WRONG - no spaces after commas
|
|
tools: TodoWrite,Read,Write
|
|
|
|
# CORRECT
|
|
tools: TodoWrite, Read, Write
|
|
```
|
|
|
|
### Missing Examples
|
|
```yaml
|
|
# 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
|
|
```
|