agent-validate-config
Validate agent YAML frontmatter and configuration. Use before committing agent changes or in CI.
When & Why to Use This Skill
The agent-validate-config skill is a specialized developer utility designed to ensure the integrity and compliance of Claude agent configurations. It automates the verification of YAML frontmatter, ensuring all required fields—such as phase, level, and tool names—adhere to specific schema requirements. By integrating this skill into development workflows, teams can prevent configuration errors, maintain consistent agent metadata, and streamline the deployment of complex multi-agent systems.
Use Cases
- Pre-commit Validation: Automatically verify agent YAML files before committing changes to a repository to ensure configuration consistency and prevent broken builds.
- CI/CD Pipeline Integration: Incorporate validation scripts into automated testing workflows to block invalid agent configurations from merging into production environments.
- Troubleshooting & Debugging: Quickly identify syntax errors, missing required fields, or invalid tool references when agents fail to load or exhibit unexpected behavior.
- Structural Auditing: Ensure that all agents within a project follow the correct directory structure and naming conventions (kebab-case) for better maintainability.
| name | agent-validate-config |
|---|---|
| description | "Validate agent YAML frontmatter and configuration. Use before committing agent changes or in CI." |
| mcp_fallback | none |
| category | agent |
| user-invocable | false |
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 configurationsCLAUDE.md- Agent system guidelines