agent-validate-config
Validate agent YAML frontmatter and configuration files to ensure correct structure, required fields, and proper tool specifications. Use when creating or modifying agent configurations.
- Category: discovered
- Tags: github, community
- Version: 1.0.0
- Author: walid
- Downloads: 0
- GitHub stars: 4
- Updated: 2025-11-21
Download the latest version (v1.0.0) from this page.
SKILL.md
---
name: agent-validate-config
description: Validate agent YAML frontmatter and configuration files to ensure correct structure, required fields, and proper tool specifications. Use when creating or modifying agent configurations.
---
# Agent Configuration Validation Skill
This skill validates agent configuration files to ensure they meet ML Odyssey's agent system requirements.
## When to Use
- User asks to validate agent configs (e.g., "validate agent configurations")
- After creating new agent configuration
- Before committing agent config changes
- CI/CD validation before merge
- Troubleshooting agent loading issues
## What Gets Validated
### YAML Frontmatter
Required fields:
```yaml
---
name: agent-name
role: Agent Role
level: 0-5
phase: Plan|Test|Implementation|Package|Cleanup
description: Brief description
tools: ["Read", "Write", "Bash"]
delegates_to: ["other-agent"]
escalates_to: ["parent-agent"]
---
```text
### Configuration Checks
1. **Syntax** - Valid YAML format
1. **Required fields** - All mandatory fields present
1. **Field values** - Correct types and values
1. **Tool specs** - Valid tool names
1. **Delegation** - Valid agent references
1. **File location** - Correct directory structure
## Usage
### Validate Single Agent
```bash
# Validate specific agent
./scripts/validate_agent.sh .claude/agents/implementation-specialist.md
# Example output
# ✅ Valid YAML frontmatter
# ✅ All required fields present
# ✅ Tools are valid
# ✅ Delegation targets exist
```text
### Validate All Agents
```bash
# Validate all agent configs
python3 tests/agents/validate_configs.py .claude/agents/
# Or use script
./scripts/validate_all_agents.sh
```text
### CI Validation
Runs automatically in CI:
```bash
# .github/workflows/test-agents.yml
python3 tests/agents/validate_configs.py .claude/agents/
```text
## Required Fields
### Mandatory
- `name` - Agent identifier (kebab-case)
- `role` - Human-readable role
- `level` - Hierarchy level (0-5)
- `phase` - Development phase
- `description` - Brief description
### Optional
- `tools` - List of tool names
- `delegates_to` - List of delegate agent names
- `escalates_to` - List of parent agent names
- `skills` - List of skill names
## Validation Rules
### Name Format
```yaml
# ✅ Correct
name: implementation-specialist
# ❌ Wrong
name: Implementation Specialist # No spaces
name: impl_specialist # No underscores
```text
### Level Range
```yaml
# ✅ Correct
level: 3 # 0-5 only
# ❌ Wrong
level: 10 # Out of range
level: "3" # Must be integer
```text
### Phase Values
```yaml
# ✅ Correct
phase: Implementation
phase: Plan
phase: Test
# ❌ Wrong
phase: Development # Not a valid phase
```text
### Tool Names
```yaml
# ✅ Correct
tools: ["Read", "Write", "Bash", "Grep", "Glob"]
# ❌ Wrong
tools: ["FileRead"] # Invalid tool name
tools: "Read" # Must be array
```text
## Error Messages
### Missing Fields
```text
❌ Validation failed: .claude/agents/agent.md
Missing required field: 'level'
```text
**Fix:** Add missing field to YAML frontmatter
### Invalid Tool
```text
❌ Invalid tool: 'InvalidTool'
Valid tools: Read, Write, Bash, Grep, Glob
```text
**Fix:** Use correct tool name from valid set
### Invalid Reference
```text
❌ Delegation target not found: 'nonexistent-agent'
```text
**Fix:** Verify agent name is correct or create referenced agent
## Examples
### Validate specific agent:
```bash
./scripts/validate_agent.sh .claude/agents/implementation-specialist.md
```text
### Validate all agents:
```bash
python3 tests/agents/validate_configs.py .claude/agents/
```text
### Fix validation errors:
```bash
# Run validation
./scripts/validate_agent.sh .claude/agents/my-agent.md
# Read errors
# Fix frontmatter
# Re-validate
./scripts/validate_agent.sh .claude/agents/my-agent.md
```text
## Scripts Available
- `scripts/validate_agent.sh` - Validate single agent
- `scripts/validate_all_agents.sh` - Validate all agents
- `tests/agents/validate_configs.py` - Python validation script
## Integration with Workflow
### Pre-commit Hook
```yaml
- repo: local
hooks:
- id: validate-agents
name: Validate Agent Configs
entry: python3 tests/agents/validate_configs.py
language: system
files: ^\.claude/agents/.*\.md$
```text
### CI Pipeline
```yaml
- name: Validate Agent Configurations
run: python3 tests/agents/validate_configs.py .claude/agents/
```text
## Common Errors
### 1. YAML Syntax Error
```text
Error parsing YAML: mapping values are not allowed here
```text
**Fix:** Check for proper YAML indentation and syntax
### 2. Missing Delimiter
```text
Error: No YAML frontmatter found
```text
**Fix:** Ensure file starts with `---` and ends frontmatter with `---`
### 3. Duplicate Keys
```text
Error: Duplicate key: 'name'
```text
**Fix:** Remove duplicate keys in frontmatter
## Best Practices
1. **Validate before commit** - Always validate after changes
1. **Use templates** - Start from agent templates
1. **Check references** - Ensure delegated agents exist
1. **Valid tools only** - Use documented tool names
1. **Correct levels** - Verify level matches hierarchy
See `/agents/templates/` for agent configuration templates.