CAPS Format Validator Skill

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:

YAML frontmatter between --- markers
title field in frontmatter
description field in frontmatter
allowed_tools array in frontmatter
Main content after frontmatter
## 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

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

Agent Skills: CAPS Format Validator

Skill Files