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