Context
- Agent definitions:!
find.claude/agents -name "*.md" -not -name "settings*" - Settings file:!
find.claude/agents -maxdepth 1 -name "settings.local.json" -type f
Your task
1. Discovery Phase
- Use Glob to find all agent definition files in
.claude/agents/ - Read each agent file to extract frontmatter and configuration
- Identify the settings.local.json for permission overrides
2. Frontmatter Validation
For each agent, verify required fields are present:
- ✅ name: Agent identifier (must match filename)
- ✅ model: Claude model to use (e.g., "claude-opus-4-7")
- ✅ color: Hex color code for UI (e.g., "#E53E3E")
- ✅ description: Clear usage guidance with "Use proactively when..."
- ✅ tools: Tool list or "All" for full access
Flag issues:
- Missing required fields
- Mismatched name vs filename
- Invalid model names
- Malformed color codes
3. Tool Assignment Analysis
Evaluate tool assignments for security and appropriateness:
Read-only agents (should NOT have write access):
- research-documentation
- code-analysis (read only)
- code-review (read + LSP only)
- security-audit (read + LSP + Bash for scanning)
Write-enabled agents (appropriate write access):
- code-refactoring (Edit, MultiEdit)
- documentation (Write, MultiEdit)
- cicd-pipelines (Write, Edit, GitHub)
Special privileges (validate necessity):
- Bash access (security-audit, system-debugging, cicd-pipelines, test-architecture)
- GitHub access (cicd-pipelines, commit-review)
- Zen MCP access (system-debugging only)
- All tools access (should be rare, validate justification)
LSP tool assignments (language-specific):
- Verify LSP tools match agent's language focus
- security-audit should have broad LSP coverage (6+ servers)
- code-review should have multi-language LSP support
- code-analysis should have appropriate LSP access
4. Security Assessment
Check for potential security issues:
Overprivileged agents:
- Agents with "All" tools without clear justification
- Read-only agents with write/edit capabilities
- Unnecessary Bash or GitHub access
- Research agents with modification permissions
Missing restrictions:
- settings.local.json should have deny rules for destructive operations
- Allow list should be minimal and specific
- No wildcard tool access unless justified
Privilege escalation risks:
- Agents that can modify other agent configs
- Agents with both read and execute permissions
- Cross-agent permission leakage
5. Consistency Checks
Validate configuration consistency:
Naming conventions:
- Agent names use kebab-case
- Filenames match agent names
- Descriptions follow consistent format
Model assignments:
- All agents use appropriate Claude models
- No deprecated model references
- Consistent model selection strategy
Tool groupings:
- Similar agents have similar tool sets
- No duplicate or redundant tool assignments
- Clear separation of concerns
6. Report Generation
Create comprehensive audit report with:
Executive Summary:
- Total agents audited
- Critical issues found
- Security concerns
- Overall health rating
Detailed Findings:
- ❌ Critical: Missing required fields, security violations
- ⚠️ Warnings: Overprivileged agents, inconsistencies
- ℹ️ Info: Best practice suggestions, optimization opportunities
Agent-by-Agent Analysis: For each agent, report:
- Configuration completeness (✅/❌ for each required field)
- Tool assignment appropriateness (✅/⚠️/❌)
- Security assessment (safe/review/risk)
- Recommendations for improvement
Action Items:
- Immediate fixes required (with file paths and line numbers)
- Optional improvements
- Configuration validation passed/failed
7. Output Format
Structure the report as:
# Claude Agent Configuration Audit
## Executive Summary
- **Total Agents**: X
- **Configuration Issues**: Y
- **Security Concerns**: Z
- **Health Rating**: [EXCELLENT|GOOD|NEEDS_WORK|CRITICAL]
## Critical Issues
[List any critical problems requiring immediate fix]
## Agent Analysis Table
| Agent | Model | Tools | Color | Status | Notes |
| ---------- | ----- | -------- | ----- | --------- | ------ |
| agent-name | ✅/❌ | ✅/⚠️/❌ | ✅/❌ | PASS/FAIL | Issues |
## Security Assessment
[Tool privilege analysis and security concerns]
## Recommendations
[Prioritized action items with file paths]
## Detailed Findings
[Per-agent breakdown with specific issues]8. Best Practices Reference
Tool access principles:
- Least privilege principle for tool access
- Clear separation between read-only and write-enabled agents
- Appropriate LSP tool coverage for language-specific work
- Minimal Bash access (only when required)
- Restricted GitHub access (only for git-ops and CI/CD)
Configuration standards:
- All required frontmatter fields present
- Consistent model selections across agents
- Appropriate tool permissions for agent role
- Clear descriptions with proactive usage guidance
9. Optional: Verbose Mode
If --verbose flag is provided:
- Show full frontmatter for each agent
- Display complete tool lists
- Include settings.local.json content
- Provide detailed fix commands for each issue
Notes
- This is a read-only audit - modifications require explicit user request
- Focus on configuration correctness and security implications
- Provide actionable recommendations with specific file locations
- Use TodoWrite to track audit progress if checking multiple agents