melodic-software/audit-agents

Audit Agents Command

Audit Claude Code subagents for quality, compliance with official documentation, and maintainability.

Initialization

Before auditing, initialize the environment:

Get the current UTC date, capture the project root path, ensure the temp directory exists, and clean up stale audit files (unless --recover). The subagent-development skill provides authoritative validation guidance (auto-loaded when this command runs).

What Gets Audited

• YAML frontmatter (name, description, tools, model, color)
• Naming conventions (lowercase kebab-case, max 64 chars)
• Description quality (third person, "PROACTIVELY use when..." guidance)
• Tool access configuration appropriateness
• Model selection correctness (haiku/sonnet/opus based on complexity)

Command Arguments

| Argument | Description | | --- | --- | | (none) | Smart mode: audit modified, never-audited, or stale (>90 days) agents | | --force | Audit ALL agents regardless of status | | --skip-validation | Skip finding validation (faster, but may include false positives) | | --plugin-only | Only audit local plugin agents | | --project-only | Only audit project agents (.claude/agents/) | | --global-only | Only audit globally installed plugin agents | | --recover | Recover results from interrupted audit | | agent-name | Audit specific agent(s) by name |

Step 1: Discover Agent Sources

Detect all agent sources in local repo and globally installed plugins.

For local discovery, check marketplace repos, single plugin repos, and .claude/agents/. Track plugin names for deduplication.

For global discovery, check ~/.claude/plugins/ (Unix) or %USERPROFILE%\.claude\plugins\ (Windows). Skip globals with local dev versions.

Step 2: Determine Audit Queue

If specific agents named, audit those. If --force, audit all. Otherwise, audit modified/stale agents.

Step 3: Present Audit Plan

Display mode, sources discovered, deduplication status, and audit queue.

Step 4: Execute Audits

For each agent, spawn the agent-auditor subagent with source, path, and last audit date. Run in parallel batches of 3-5.

Subagents write findings to .claude/temp/. The main conversation thread collects results and updates audit logs using its Write/Edit tools.

Step 4.5: Validate Findings

Unless --skip-validation flag is present:

1. Spawn the audit-finding-validator agent with:
   • project_root: The captured project root path
   • audit_type: "agent"
   • audit_files: List of .claude/temp/audit-*-agent-*.json file paths
2. Wait for validation to complete
3. Read updated JSON files with validation results
4. Filter out FALSE_POSITIVE findings completely before aggregation
5. Note: Filtered findings are logged to .claude/temp/audit-filtered-findings.json

If --skip-validation flag is present:

• Skip validation phase entirely (current speed preserved)
• Present all findings without filtering
• Note in summary: "Validation: Skipped"

Step 5: Final Summary

Report total audited by source, results, and details table. Note that global agent fixes must be applied manually.

Include validation statistics (if validation was performed):

• Validation performed: Yes/No
• Findings validated: X
• False positives filtered: Y
• Verified findings: Z
• Unverified findings: W

Scoring

• PASS (85+): Ready for use
• PASS WITH WARNINGS (70-84): Functional with improvement opportunities
• FAIL (<70): Issues that should be addressed

Audit Log Location

All audit results are written to .claude/audit/agents.md.

Use /audit-log agents to view current audit status.

Recovery

If context collapses mid-audit, use /audit-agents --recover to recover from .claude/temp/ JSON files.

Example Usage

Example 1: Audit All Agents

User: /audit-agents

Claude: Discovering agent sources...

## Audit Plan
**Mode**: SMART
- Plugin: claude-ecosystem (12 agents)
- Plugin: code-quality (3 agents)
- Deduplicated: claude-ecosystem (global skipped)

**Will audit**: 5 agents

[Spawns agent-auditor subagents]

## Audit Complete
| Source | Agent | Result | Score |
| --- | --- | --- | --- |
| plugin | code-reviewer | PASS | 100/100 |

Example 2: Audit Specific Agent

User: /audit-agents plugin:code-reviewer
Claude: PASS (Score: 100/100)