Agent Configuration Validation

Verify agent configurations meet ML Odyssey requirements.

When to Use

• Creating or modifying agent configurations
• Before committing agent config changes
• CI/CD validation before merge
• Troubleshooting agent loading issues

Quick Reference

# Validate all agents
python3 tests/agents/validate_configs.py .claude/agents/

# Validate single agent
./scripts/validate_agent.sh .claude/agents/agent-name.md

Validation Checklist

Required YAML frontmatter fields:

---
name: agent-name              # kebab-case identifier
description: "Brief desc"     # One sentence purpose
mcp_fallback: none
category: agent               # Classification
level: 0-5                    # Hierarchy level
phase: Plan|Test|Implementation|Package|Cleanup
---

Validation includes:

• YAML syntax correctness
• All required fields present
• Correct field types and values
• Valid tool names (Read, Write, Bash, Grep, Glob)
• Valid agent references in delegates_to/escalates_to
• Correct directory structure

Error Handling

| Error | Fix | |-------|-----| | No YAML frontmatter | Ensure file starts/ends with --- | | Invalid phase value | Use: Plan, Test, Implementation, Package, Cleanup | | Delegation target not found | Verify agent name or create referenced agent | | Duplicate keys | Remove duplicate entries in frontmatter | | Wrong level type | Must be integer 0-5, not string |

References

• /agents/templates/ - Agent configuration templates
• .claude/agents/ - All agent configurations
• CLAUDE.md - Agent system guidelines