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 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 ``` ### Field Details **Required Fields:** - `name`: Agent identifier (must match filename without extension) - `description`: Shown in agent list, used for agent selection - `version`: Semver for tracking changes **Role Section:** - `identity`: Who the agent is (e.g., "React Component Builder") - `expertise`: Array of skills (e.g., ["React 19", "TypeScript", "Testing"]) - `mission`: What the agent does (e.g., "Build production-ready React components") **Tools Array:** Standard Claude Code tools: ```yaml tools: - Read - Write - Edit - Bash - Glob - Grep ``` **Workflow Structure:** ```yaml instructions: workflow: - phase: "Phase 1: Discovery" objective: "Find relevant files" steps: - "Use Glob to find components" - "Use Grep to search for patterns" - "Read existing implementations" ``` --- ## YAML vs Markdown Comparison ### Simple Agent: Side-by-Side **Markdown (`simple-agent.md`):** ```markdown --- name: simple-agent description: A simple example agent version: 1.0.0 --- <role> <identity>Code Formatter</identity> <mission>Format code files according to standards</mission> </role> <instructions> 1. Read the file 2. Format using appropriate tool 3. Write back to file </instructions> ``` **YAML (`simple-agent.agent.yaml`):** ```yaml name: simple-agent description: A simple example agent version: 1.0.0 role: identity: Code Formatter mission: Format code files according to standards instructions: workflow: - phase: Format steps: - Read the file - Format using appropriate tool - Write back to file ``` ### Complex Agent: Side-by-Side **Markdown (`react-builder.md`):** ```markdown --- name: react-builder description: Build React components with tests version: 2.1.0 --- <role> <identity>React Component Builder</identity> <expertise> - React 19 with TypeScript - React Testing Library - Component patterns </expertise> </role> <instructions> <workflow> <phase number="1" name="Create Component"> <steps> <step>Create component file with TypeScript types</step> <step>Implement component logic</step> </steps> </phase> </workflow> </instructions> <examples> <example name="Button Component"> <user>Create a button component</user> <assistant>I'll create Button.tsx with props...</assistant> </example> </examples> ``` **YAML (`react-builder.agent.yaml`):** ```yaml name: react-builder description: Build React components with tests version: 2.1.0 role: identity: React Component Builder expertise: - React 19 with TypeScript - React Testing Library - Component patterns instructions: workflow: - phase: "Phase 1: Create Component" steps: - Create component file with TypeScript types - Implement component logic examples: - name: Button Component user: Create a button component assistant: I'll create Button.tsx with props... ``` **Key Difference:** YAML is ~30% shorter for structured data. --- ## Conversion Patterns ### Markdown to YAML Conversion **Conversion Rules:** 1. Extract frontmatter YAML as base 2. Parse XML-style tags to nested objects 3. Convert numbered lists to arrays 4. Flatten markdown formatting to plain strings **Example Conversion:** **Input (Markdown):** ```markdown --- name: test-agent version: 1.0.0 --- <role> <identity>Tester</identity> <expertise> - Unit testing - Integration testing </expertise> </role> <instructions> <constraints> - Always write tests first - Use TypeScript </constraints> </instructions> ``` **Output (YAML):** ```yaml name: test-agent version: 1.0.0 role: identity: Tester expertise: - Unit testing - Integration testing instructions: constraints: - Always write tests first - Use TypeScript ``` ### YAML to Markdown Conversion **Conversion Rules:** 1. Create frontmatter from top-level fields 2. Convert nested objects to XML-style tags 3. Convert arrays to markdown lists 4. Wrap in appropriate markdown structure **Example Conversion:** **Input (YAML):** ```yaml name: docs-agent version: 1.0.0 role: identity: Documentation Writer mission: Create comprehensive docs ``` **Output (Markdown):** ```markdown --- name: docs-agent version: 1.0.0 --- <role> <identity>Documentation Writer</identity> <mission>Create comprehensive docs</mission> </role> ``` ### Automated Conversion Tools **TypeScript Conversion Function:** ```typescript import yaml from 'yaml'; import { z } from 'zod'; // Convert markdown agent to YAML function markdownToYaml(markdownPath: string): string { const content = fs.readFileSync(markdownPath, 'utf-8'); // Extract frontmatter const frontmatterMatch = content.match(/^---\n([\s\S]*?)\n---/); const frontmatter = yaml.parse(frontmatterMatch?.[1] || ''); // Parse XML-like tags const role = extractRoleSection(content); const instructions = extractInstructionsSection(content); const agent = { ...frontmatter, role, instructions }; return yaml.stringify(agent); } // Convert YAML agent to markdown function yamlToMarkdown(yamlPath: string): string { const content = fs.readFileSync(yamlPath, 'utf-8'); const agent = yaml.parse(content); const { name, description, version, role, instructions, ...rest } = agent; let md = `---\n${yaml.stringify({ name, description, version })}---\n\n`; if (role) { md += `<role>\n${objectToXml(role)}</role>\n\n`; } if (instructions) { md += `<instructions>\n${objectToXml(instructions)}</instructions>\n\n`; } return md; } ``` --- ## Validation ### Schema Validation with Zod **Define Zod Schema:** ```typescript import { z } from 'zod'; const AgentSchema = z.object({ name: z.string().regex(/^[a-z0-9-]+$/), description: z.string().min(10).max(200), version: z.string().regex(/^\d+\.\d+\.\d+$/), role: z.object({ identity: z.string(), expertise: z.array(z.string()).optional(), mission: z.string() }).optional(), tools: z.array(z.enum([ 'Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep' ])).optional(), instructions: z.object({ constraints: z.array(z.string()).optional(), workflow: z.array(z.object({ phase: z.string(), objective: z.string().optional(), steps: z.array(z.string()) })).optional() }).optional(), examples: z.array(z.object({ name: z.string(), user: z.string(), assistant: z.string() })).optional() }); // Validate YAML agent function validateAgent(yamlPath: string): boolean { const content = fs.readFileSync(yamlPath, 'utf-8'); const agent = yaml.parse(content); try { AgentSchema.parse(agent); return true; } catch (error) { console.error('Validation failed:', error); return false; } } ``` ### Common Validation Errors **1. Invalid Name Format:** ```yaml # BAD name: "My Agent" # Spaces not allowed # GOOD name: my-agent ``` **2. Missing Required Fields:** ```yaml # BAD - missing version name: test-agent description: Test agent # GOOD name: test-agent description: Test agent version: 1.0.0 ``` **3. Invalid Semver:** ```yaml # BAD version: "1.0" # Not semver # GOOD version: "1.0.0" ``` **4. Invalid Tool Names:** ```yaml # BAD tools: - ReadFile # Wrong name # GOOD tools: - Read - Write ``` **5. Incorrect Array Format:** ```yaml # BAD expertise: Unit testing, Integration testing # GOOD expertise: - Unit testing - Integration testing ``` ### Validation Tools **CLI Validator:** ```bash # Create validation script cat > validate-agent.ts <<'EOF' #!/usr/bin/env bun import { AgentSchema } from './agent-schema'; import yaml from 'yaml'; const file = process.argv[2]; const content = await Bun.file(file).text(); const agent = yaml.parse(content); const result = AgentSchema.safeParse(agent); if (result.success) { console.log('✓ Valid agent definition'); } else { console.error('✗ Validation errors:'); result.error.issues.forEach(issue => { console.error(` - ${issue.path.join('.')}: ${issue.message}`); });