Agent YAML Frontmatter Schema Reference

Agent YAML Frontmatter Schema Reference

Complete specification for Claude Code agent frontmatter fields (January 2026).

Sources

• Create Custom Subagents (accessed 2026-01-28)
• Agent Frontmatter Schema (accessed 2026-01-28)
• Tools Reference (accessed 2026-01-28)
• Skills Reference (accessed 2026-01-28)
• Validation implementation: ./../../scripts/validate_frontmatter.py

For plugin agent integration, see Claude Plugins Reference

Required Fields

name

• Type: string
• Max Length: 64 characters
• Format: lowercase letters, numbers, hyphens only
• Purpose: Unique identifier for the agent

name: code-reviewer          # Good
name: Code_Reviewer          # Invalid - uppercase, underscores
name: my-super-awesome-long-agent-name-that-exceeds-the-limit  # Invalid - too long

description

• Type: string
• Max Length: 1024 characters (first 1024 chars most important)
• Purpose: Claude uses this to decide when to delegate tasks to this agent

Follow the official Anthropic guidance in the write-frontmatter-description skill.

Must be complete and informative, explaining what the agent does and when to use it. Include trigger scenarios, file types, or tasks.

# Good - complete and informative
description: 'Review Python code for security vulnerabilities, performance issues, and PEP 8 compliance. Handles code reviews after changes complete or when reviewing pull requests. Specializes in async/await patterns.'

# Bad - too vague
description: Helps with Python

YAML Multiline Bug

Do NOT use YAML multiline indicators (>-, |, |-) for descriptions. Claude Code's indexer does not parse them correctly - the description appears as ">-" instead of actual content.

# WRONG - will show ">-" as description
description: >-
  This is a multiline
  description that breaks.

# CORRECT - single quoted string
description: 'This works correctly. Use single quotes for descriptions with special characters or keep on one line.'

Optional Fields

model

• Type: string
• Default: inherit (uses the same model as the main conversation)
• Options: sonnet, opus, haiku, inherit

model: sonnet

When to Use model: inherit

The inherit option makes the agent use the same model as the parent conversation rather than a fixed model.

Use model: inherit when:

1. Context-appropriate capability - Agent should match user's model choice

   • User chose Opus for complex work → agent gets Opus
   • User chose Haiku for speed → agent gets Haiku
   • Agent adapts to conversation context

2. User-controlled cost/capability trade-off - Let user decide model via conversation settings

   • User sets model at conversation level
   • Agent respects that choice automatically
   • No need to change agent configuration

3. Flexible workflows - Agent is used in multiple contexts with different needs

   • Research phase (might use Haiku for speed)
   • Implementation phase (might use Opus for complexity)
   • Same agent, different requirements per context

Use explicit model (sonnet, opus, haiku) when:

1. Task requires specific capability - Agent needs minimum model capability

   • Complex debugging always needs opus
   • Simple file search always works with haiku
   • Task complexity is known and fixed

2. Cost control - Prevent unexpected high costs

   • Read-only analyzer should stay haiku even if parent uses Opus
   • Prevents accidental expensive operations

3. Consistent behavior - Agent must perform the same way every time

   • Production agents with SLAs
   • Agents where capability variance is unacceptable

Decision Tree:

Does the task REQUIRE a specific model capability?
├─ Yes → Use explicit model (opus/sonnet/haiku)
└─ No → Should the agent adapt to user's choice?
   ├─ Yes → Use `inherit`
   └─ No → Use `sonnet` (safe default)

Examples:

# Inherit - adapts to conversation context
name: general-helper
model: inherit
description: Helps with various tasks matching conversation complexity

# Explicit Haiku - always fast and cheap
name: file-searcher
model: haiku
description: Search files for patterns (simple task)

# Explicit Opus - always maximum capability
name: architecture-reviewer
model: opus
description: Review system architecture for flaws (complex task)

# Explicit Sonnet - balanced default
name: code-writer
model: sonnet
description: Write production code (moderate complexity)

tools

• Type: string (comma-separated scalar; NOT a YAML array)
• Default: Inherited from parent conversation
• Purpose: ALLOWLIST - only these tools available

# CORRECT: comma-separated string format
tools: Read, Grep, Glob, Bash

# Pattern matching for specific commands
tools: Bash(git:*), Bash(npm:install)

Available Tools: Read, Write, Edit, Bash, Grep, Glob, NotebookEdit, AskUserQuestion, WebSearch, Task, ToolSearch, Skill

Note: MCP tools from installed servers are also available and follow pattern mcp__server-name__tool-name

Pattern Matching Examples:

# Allow only specific git commands
tools: Bash(git:status), Bash(git:log), Bash(git:diff)

# Allow git read operations only
tools: Bash(git:status|log|diff|show)

# Allow all git commands
tools: Bash(git:*)

# Combine with other tools
tools: Read, Grep, Bash(git:*), Bash(npm:install)

disallowedTools

• Type: string (comma-separated scalar; NOT a YAML array)
• Default: none
• Purpose: DENYLIST - remove from inherited tools

disallowedTools: Write, Edit, Bash

permissionMode

• Type: string
• Default: default
• Options:

permissionMode: acceptEdits

skills

• Type: string (comma-separated scalar; NOT a YAML array)
• Default: none (skills NOT inherited)
• Purpose: Load skill content into agent context

# CORRECT: comma-separated string
skills: python-development, testing-patterns, security-best-practices

Important: Agents do NOT inherit skills from parent conversation. Must explicitly list needed skills.

hooks

• Type: object
• Default: none
• Purpose: Lifecycle hooks scoped to this agent

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate.sh"
          timeout: 5000
  PostToolUse:
    - matcher: "Write|Edit"
      hooks:
        - type: command
          command: "./scripts/lint.sh"
  Stop:
    - hooks:
        - type: command
          command: "./scripts/cleanup.sh"

Hook Events:

• PreToolUse - Before tool executes (can block with exit 2)
• PostToolUse - After tool succeeds
• PostToolUseFailure - After tool fails
• PermissionRequest - When permission needed
• UserPromptSubmit - When user submits prompt
• Notification - When notifications are sent
• Stop - When agent completes
• SubagentStart - When child agent starts
• SubagentStop - When child agent completes
• Setup - During initialization
• SessionStart - At session beginning
• SessionEnd - At session end
• PreCompact - Before conversation compaction

For complete hook reference, see Claude Hooks Reference

color

• Type: string
• Default: none
• Purpose: UI-only visual identifier for the subagent in Claude Code

Notes:

• The official "Create custom subagents" docs describe choosing a color to help identify which subagent is running in the UI: https://code.claude.com/docs/en/sub-agents.md
• No behavioral effect is described (does not change delegation logic, tools, permissions, model, hooks, or the system prompt).

color: cyan      # Analysis agents
color: yellow    # Warning/optimization
color: green     # Success/validation
color: orange    # Audit/review
color: red       # Error handling

argumentHint

• Type: string
• Default: none
• Purpose: Hint text shown to users when invoking the agent manually
• Note: Less commonly used; primarily for user-facing CLI hints

argumentHint: '<file-path> [options]'

alwaysLoadSkills

• Type: boolean
• Default: false
• Purpose: When true, load agent's skills into context even when agent is not directly invoked
• Use Case: Rare; for agents that provide skills to parent conversation

alwaysLoadSkills: true

Complete Example

---
name: security-auditor
description: 'Audit code for security vulnerabilities including OWASP Top 10, injection risks, and authentication flaws. Use when reviewing security-sensitive code or before production deployment. Proactively invoked after changes to auth or data handling code.'
model: opus
tools: Read, Grep, Glob, Bash(git:log), Bash(git:diff)
disallowedTools: Write, Edit
permissionMode: dontAsk
skills: security-best-practices, owasp-guidelines
hooks:
  Stop:
    - hooks:
        - type: command
          command: "./scripts/log-audit.sh"
color: red
---

Plugin Integration

When creating agents for plugins, additional considerations apply:

Location: {plugin-root}/agents/ directory

Registration: Agents must be listed in plugin.json:

{
  "name": "my-plugin",
  "agents": ["./agents/security-reviewer.md", "./agents/code-formatter.md"]
}

Important: The agents field in plugin.json must be an array of individual file paths, NOT a directory string:

// CORRECT
"agents": ["./agents/reviewer.md", "./agents/tester.md"]

// INCORRECT - will fail validation
"agents": "./agents/"

Validation: After creating plugin agents:

# Validate frontmatter
uv run plugins/plugin-creator/scripts/validate_frontmatter.py validate ./agents/my-agent.md

# Validate complete plugin
claude plugin validate ./path/to/plugin

For complete plugin reference, see Claude Plugins Reference

Validation Rules

Before saving an agent, verify:

1. name

   • Lowercase only
   • Only letters, numbers, hyphens
   • Max 64 characters
   • Unique in project

2. description

   • Max 1024 characters
   • Contains action verbs
   • Contains trigger phrases
   • Contains relevant keywords

3. model (if specified)

   • Valid option: sonnet, opus, haiku, inherit

4. tools (if specified)

   • All tools are valid tool names
   • Pattern syntax correct for Bash restrictions

5. skills (if specified)

   • All skills exist in project

6. permissionMode (if specified)

   • Valid option with justification if bypassPermissions

7. YAML syntax

   • Valid YAML
   • Proper quoting for multiline strings
   • No trailing commas or syntax errors
   • No YAML multiline indicators (>-, |-) in description field

Automated Validation

Use the validation script for comprehensive checks:

# Validate single agent
uv run plugins/plugin-creator/scripts/validate_frontmatter.py validate ./agents/my-agent.md

# Auto-fix common issues (dry-run first)
uv run plugins/plugin-creator/scripts/validate_frontmatter.py fix ./agents/my-agent.md --dry-run

# Batch validation
uv run plugins/plugin-creator/scripts/validate_frontmatter.py batch ./agents/

# Batch fix
uv run plugins/plugin-creator/scripts/validate_frontmatter.py fix-batch ./agents/

What the validator checks:

• YAML syntax validity
• Required fields presence (name, description)
• Field type correctness (string, boolean, object)
• Field value constraints (length, format, enumeration)
• Tool/skill format (comma-separated strings, not YAML arrays)
• Forbidden multiline indicators

What the validator auto-fixes:

• YAML arrays → comma-separated strings
• Multiline descriptions → single-line quoted strings
• Unquoted descriptions with special characters

SOURCE: validate_frontmatter.py lines 103-187

Related Documentation

• Claude Skills Reference - Skills system overview
• Claude Plugins Reference - Plugin integration
• Claude Hooks Reference - Hook configuration