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

```yaml
# 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 missio