yaml-agent-format

YAML Agent Format

Overview

Why YAML for Agents?

YAML provides an alternative format for defining Claude Code agents with several advantages:

Benefits:

• Machine-parseable: Easy to validate, transform, and generate programmatically
• Less verbose: No markdown headers, cleaner structure
• Schema validation: Strong typing with JSON Schema or Zod
• Tooling support: Better IDE autocomplete, linting, formatting
• Data-first: Natural for configuration management

Trade-offs:

• Less readable: Markdown is better for long-form documentation
• Indentation-sensitive: YAML whitespace can be error-prone
• No rich formatting: Can't use markdown tables, code blocks in descriptions

When to Use YAML vs Markdown

Use YAML when:

• Generating agents programmatically
• Agent definitions are data-heavy (many examples, tools, rules)
• You need strong schema validation
• Agent is simple and concise
• Working in automation/CI pipelines

Use Markdown when:

• Agent has extensive documentation needs
• You want rich formatting (tables, diagrams, code examples)
• Agent is tutorial-like with explanations
• Human readability is priority
• Agent includes narrative instructions

Compatibility with Claude Code

YAML agents are fully compatible with Claude Code:

• Placed in agents/ directory with .agent.yaml extension
• Registered in plugin.json identically to markdown agents
• Loaded and executed the same way
• Can mix YAML and markdown agents in same plugin

---

YAML Agent Schema

Complete Schema Definition

# Required fields
name: string                    # Agent name (kebab-case)
description: string             # Brief description (1-2 sentences)
version: string                 # Semver version (e.g., "1.0.0")

# Optional but recommended
role:
  identity: string              # Agent's role/identity
  expertise: string[]           # List of expertise areas
  mission: string               # Primary mission statement

tools: string[]                 # Available tools (Read, Write, Edit, Bash, etc.)

instructions:
  constraints: string[]         # Critical constraints/rules
  workflow:                     # Step-by-step workflow
    - phase: string             # Phase name
      objective: string         # Phase objective
      steps: string[]           # List of steps

knowledge:                      # Knowledge base entries
  - topic: string               # Knowledge topic
    content: string             # Knowledge content

examples:                       # Usage examples
  - name: string                # Example name
    user: string                # User message
    assistant: string           # Assistant response

formatting:
  style: string                 # Communication style
  templates:                    # Output templates
    success: string
    error: string