meta-audit
Audit Claude subagent configs for completeness, security, and best practices. Use when reviewing agents/ for missing frontmatter, overprivileged tools, or bad model choices.
How do I install this agent skill?
npx skills add https://github.com/laurigates/claude-plugins --skill meta-auditIs this agent skill safe to install?
- Gen Agent Trust Hubpass
This skill provides a structured framework for auditing AI agent configuration files for security and consistency. It uses standard shell commands to discover configuration files within the project and instructs the agent to perform a read-only assessment of tool permissions and metadata completeness.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
- Runlayerwarn
1/1 file flagged
What does this agent skill do?
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); recommendlowwhere 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:
# 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"
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/laurigates/claude-plugins/meta-audit">View meta-audit on skillZs</a>