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-5")

• ✅ 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

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