schemas

plugin: agentdev updated: 2026-01-20 # 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: TaskCreate, TaskUpdate, TaskList, TaskGet, 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`, `TaskCreate, TaskUpdate, TaskList, TaskGet`, `Read`, `Bash` - Often: `AskUserQuestion`, `Glob`, `Grep` - Never: `Write`, `Edit` **Planners:** - Must have: `TaskCreate, TaskUpdate, TaskList, TaskGet`, `Read`, `Write` (for docs) - Often: `Glob`, `Grep`, `Bash` **Implementers:** - Must have: `TaskCreate, TaskUpdate, TaskList, TaskGet`, `Read`, `Write`, `Edit` - Often: `Bash`, `Glob`, `Grep` **Reviewers:** - Must have: `TaskCreate, TaskUpdate, TaskList, TaskGet`, `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, TaskCreate, TaskUpdate, TaskList, TaskGet 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: TaskCreate, TaskUpdate, TaskList, TaskGet,Read,Write # CORRECT tools: TaskCreate, TaskUpdate, TaskList, TaskGet, 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 ```