yaml-agent-format

What this skill does

# 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.stringi