CAPS Format Validator

Purpose

Validate CAPS playbooks to ensure correct formatting, completeness, and compatibility with both Claude Code Skills and Goose Recipes. Catch errors early before conversion or deployment.

Prerequisites

• CAPS playbook file to validate (playbook.md)
• Python 3 (optional, for YAML validation)
• Basic understanding of CAPS format

CAPS Format Requirements

Every valid CAPS playbook must have:

1. YAML frontmatter between --- markers
2. title field in frontmatter
3. description field in frontmatter
4. allowed_tools array in frontmatter
5. Main content after frontmatter
6. ## Instructions or ## Steps section

Instructions

Step 1: Check File Structure

# Verify file exists
if [ ! -f "playbook.md" ]; then
    echo "❌ Error: playbook.md not found"
    exit 1
fi

# Check file not empty
if [ ! -s "playbook.md" ]; then
    echo "❌ Error: playbook.md is empty"
    exit 1
fi

echo "✅ File structure valid"

Step 2: Validate YAML Frontmatter

Check that frontmatter exists and is valid YAML syntax between --- markers.

Step 3: Check Required Fields

# Check for title
if ! grep -q "^title:" playbook.md; then
    echo "❌ Missing required field: title"
    exit 1
fi

# Check for description
if ! grep -q "^description:" playbook.md; then
    echo "❌ Missing required field: description"
    exit 1
fi

# Check for allowed_tools
if ! grep -q "^allowed_tools:" playbook.md; then
    echo "❌ Missing required field: allowed_tools"
    exit 1
fi

Step 4: Validate Content Structure

Check for Instructions section, code blocks, and step markers.

Step 5: Test Conversion Compatibility

Verify the playbook can convert to both Claude Skills and Goose Recipes formats.

Step 6: Check Best Practices

Check for Prerequisites, Validation, and Troubleshooting sections.

Validation

Playbook is valid when:

• Has YAML frontmatter between --- markers
• Includes title, description, allowed_tools
• allowed_tools is YAML array
• Has ## Instructions section
• Includes code examples
• Can convert to Claude Skills
• Can convert to Goose Recipes
• Passes validator with zero errors

Common Errors

Error: Missing frontmatter

❌ Wrong:
# My Playbook

✅ Correct:
---
title: My Playbook
---

Error: Incorrect tool format

❌ Wrong:
allowed_tools: kubectl, helm

✅ Correct:
allowed_tools:
  - kubectl
  - helm

Best Practices

1. Test Before Committing: Always validate locally
2. Use Templates: Start with valid template
3. Include Examples: Show commands and output
4. Add Validation: Define success criteria
5. Version Playbooks: Use semantic versioning