schemas

Claude Code 代理和命令的 YAML frontmatter 模式。在创建或验证代理/命令文件时使用。

SKILL.md

--- frontmatter

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