agent-audit

Agent Audit

Audit a Claude Code agent/subagent for quality, routing mesh compliance, and correctness. Each issue is presented one at a time with multiple resolution options, always including a research option that forks parallel code + web research agents.

Input

$ARGUMENTS — path to the agent .md file.

Parse Arguments

Extract from $ARGUMENTS:

• Agent Path: Path to the .md file
• Verify the file exists and has .md extension. If not found, report error and stop.
• Extract agent name from filename (without .md extension).

Process

Phase 1: Load Documents

1. Read the agent .md file.
2. Read the audit checklist at ${CLAUDE_SKILL_DIR}/references/checklist.md.
3. Parse the frontmatter (YAML between --- delimiters) and body content separately.
4. Scan the agent's sibling directory for other agents (to check routing mesh references).
5. Optionally scan other installed plugin agent directories to verify cross-delegation targets exist.

Phase 2: Run All Checks

Evaluate every check from the checklist against the loaded agent. For each check:

• Determine status: PASS, FAIL, or N/A
• For FAIL: record the severity and a specific description of what's wrong

Build a prioritized issue queue:

1. 🔴 CRITICAL issues first
2. 🟡 WARNING issues next
3. 🔵 INFO issues last
4. ❓ Open Questions last

Phase 3: Present Summary

## Agent Audit Summary: [agent name]

**File:** [path]
**Lines:** [line count]
**Routing Mesh:** [delegation targets found, if any]

Found **N issues** and **M open questions**:
- 🔴 CRITICAL: [count]
- 🟡 WARNING: [count]
- 🔵 INFO: [count]
- ❓ Open Questions: [count]

Starting sequential resolution...

If zero issues found, skip to Phase 5 with PASS verdict.

Phase 4: Sequential Resolution

For each issue, present using AskUserQuestion with:

• Clear description of the issue and which checklist item it violates
• At least 2 fix options (one marked ⭐ recommended)
• Always include "🔍 Research code & web" option
• Always include "Skip" as last option