Validates and reviews Claude Code agents/subagents against best practices. Checks YAML syntax, naming conventions, description quality, system prompt effectiveness, and tool configuration. Provides improvement suggestions and optionally applies fixes. Use when validating agents, reviewing agent quality, checking agents before commit, or when `--check-agent` or `--validate-agent` is mentioned.
This skill is limited to using the following tools:
Validate and review Claude Code agents/subagents against best practices and quality standards. Combines validation (catch errors) and review (suggest improvements) in one pass.
# User agents
~/.claude/agents/[agent-name].md
# Project agents
.claude/agents/[agent-name].md
Use Read to examine:
Use TodoWrite to track validation and review items.
Required Fields:
name present and non-emptydescription present and non-emptySyntax:
--- on line 1--- before contentOptional Fields:
tools (if present) uses comma-separated valid tool namesmodel (if present) is sonnet, opus, haiku, or inheritcolor (if present) is a valid color name[role]-[specialty] or [specialty] patternGood: code-reviewer, test-runner, debugger
Bad: helper, my-agent, the-best-agent
Structure:
Quality:
Anti-patterns:
Structure:
Quality:
Anti-patterns:
If tools field present:
Common patterns:
Read, Grep, Glob, BashRead, Write, BashIf model field present:
sonnet, opus, haiku, or inheritAfter validation passes, review for improvements:
# Agent Check Report: [Agent Name]
## Summary
- **Status**: PASS / FAIL / WARNINGS
- **Location**: [path]
- **Issues**: [count critical] / [count warnings]
## Validation Results
### YAML Frontmatter
[Status and details]
### Naming Conventions
[Status and details]
### Description Quality
[Status and details]
### System Prompt
[Status and details]
### Tool Configuration
[Status and details]
### Model Configuration
[Status and details]
## Critical Issues (must fix)
1. [Issue with specific fix]
## Warnings (should fix)
1. [Issue with specific fix]
## Improvement Suggestions
1. [Suggestion with before/after]
## Strengths
- [What's done well]
For each issue:
Current:
description: Helps with debugging
Problem: Too vague, no trigger keywords
Fix:
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
Impact: Specific purpose, trigger keywords, proactive invocation.
Current:
You are a helpful debugging assistant.
Problem: No process, no specifics
Fix:
You are an expert debugger specializing in root cause analysis.
When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works
Impact: Clear process, actionable steps.
Ask before making changes:
Found [N] issues:
- [Critical issues]
- [Warnings]
- [Suggestions]
Would you like me to apply these fixes?
If approved, use Edit to make changes.
Critical (must fix):
Important (should fix):
Nice-to-have:
# Find agent files
ls ~/.claude/agents/*.md
ls .claude/agents/*.md
# Search by name
find ~/.claude/agents .claude/agents -name "*.md" 2>/dev/null
# Check for tabs
grep -P "\t" ~/.claude/agents/agent-name.md
# View frontmatter
head -n 20 ~/.claude/agents/agent-name.md
After creating an agent:
subagent-authoring → subagent-check → iterate until passing
Before committing:
subagent-check → fix critical issues → commit