schemas

YAML frontmatter schemas for Claude Code agents and commands. Use when creating or validating agent/command files.

⭐193stars🔀17forks📁View on GitHub🕐Updated Dec 30, 2025⬇️2downloads

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.
nameschemas
descriptionYAML 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
  • 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

# 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