schemas
YAML frontmatter schemas for Claude Code agents and commands. Use when creating or validating agent/command files.
When & Why to Use This Skill
This Claude skill provides comprehensive YAML frontmatter schemas and validation rules for Claude Code agents and commands. It ensures structural integrity and consistency when defining agent metadata, tool permissions, and operational workflows, streamlining the development and deployment of custom AI agents.
Use Cases
- 1. Agent Configuration: Defining essential metadata such as name, model selection, and terminal color coding for custom Claude agents to ensure they are correctly identified and rendered.
- 2. Workflow Validation: Utilizing the schema to validate command files, ensuring that mandatory fields like 'allowed-tools' and 'description' are present and follow the required multi-line format.
- 3. Tool Permission Management: Standardizing the assignment of specific tools (e.g., Bash, Read, Write) to appropriate agent roles (Orchestrators, Planners, Implementers) to maintain operational security and functional logic.
- 4. Error Prevention and Debugging: Identifying common YAML syntax errors, such as missing colons or incorrect tool list formatting, before agent execution to reduce development friction.
| name | schemas |
|---|---|
| description | YAML frontmatter schemas for Claude Code agents and commands. Use when creating or validating agent/command files. |
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: 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
---
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 -
nameis lowercase-with-hyphens -
descriptionincludes 3+ examples -
modelis valid (sonnet/opus/haiku) -
toolsis comma-separated with spaces - Closing
---present - No YAML syntax errors
Command Frontmatter
- Opening
---present -
descriptionexplains workflow -
allowed-toolsincludes Task 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: TodoWrite,Read,Write
# CORRECT
tools: TodoWrite, 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