meta-audit

# meta-audit ## When to Use This Skill | Use this skill when... | Use custom-agent-definitions instead when... | |---|---| | Reviewing existing `.claude/agents/*.md` files for missing frontmatter, overprivileged tools, or wrong models | Authoring a new agent definition file from scratch | | Validating read-only vs write-enabled agent privilege boundaries before committing | Configuring a single agent's `model`, `allowed-tools`, or `context: fork` | | Auditing agents across an entire project for naming and security consistency | Copying or generalising another project's agents (use meta-assimilate) | ## Context - Agent definitions: !`find . -path '*/.claude/agents/*' -name "*.md" -not -name "settings*"` - Settings file: !`find . -path '*/.claude/agents/*' -maxdepth 3 -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**: an alias (`opus`, `fable`, `sonnet`, `haiku`, `inherit`) or a current full ID (e.g. `claude-fable-5-1`); a dated ID from a superseded generation (`claude-opus-4-7`, `claude-sonnet-4-6`) is a finding — recommend the alias unless the pin is deliberate - ℹ️ **effort**: optional `low`…`max` (overrides the session effort while the agent runs; default inherits); recommend `low` where the body describes mechanical work - ✅ **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: ```markdown # 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 - Keep the per-agent status table (§7) as your running record while checking multiple agents; the task/todo tools (TodoWrite, TaskCreate…) are unavailable on Opus 4.8+/Sonnet 5/Fable unless opted in — see `.claude/rules/agentic-permissions.md` § "Task-tool availability"