Agent-Skills.md

Agent Skills: Audit Agents Command

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

UncategorizedID: melodic-software/claude-code-plugins/audit-agents

Repository

melodic-software/claude-code-plugins
melodic-softwareLicense: MIT
417

Install this agent skill to your local

pnpm dlx add-skill https://github.com/melodic-software/claude-code-plugins/tree/HEAD/plugins/claude-ecosystem/skills/audit-agents

Skill Files

Browse the full folder contents for audit-agents.

Download Skill

Loading file tree…

plugins/claude-ecosystem/skills/audit-agents/SKILL.md

Skill Metadata

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

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)