schemas

plugin: agentdev updated: 2026-01-20

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: TaskCreate, TaskUpdate, TaskList, TaskGet, Read, Write  # Required: comma-separated, space after comma
skills: skill1, skill2         # Optional: referenced skills
---

Field Reference

Color Guidelines

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

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

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

# WRONG - missing colon
name agent-name

# CORRECT
name: agent-name

Incorrect Tool Format

# WRONG - no spaces after commas
tools: TaskCreate, TaskUpdate, TaskList, TaskGet,Read,Write

# CORRECT
tools: TaskCreate, TaskUpdate, TaskList, TaskGet, 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