Skip to main content
Generalmelodic-software

audit-agents

Audit Claude Code subagents for quality, compliance, and maintainability. Use after creating or modifying agents, before releases, or for periodic quality checks.

Stars
74
Source
melodic-software/claude-code-plugins
Updated
2026-04-07
Slug
melodic-software--claude-code-plugins--audit-agents
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/melodic-software/claude-code-plugins/HEAD/plugins/claude-ecosystem/skills/audit-agents/SKILL.md -o .claude/skills/audit-agents.md

Drops the SKILL.md into .claude/skills/audit-agents.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

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)