Agent Audit analyzes cumulative agent usage data to identify unused, rarely-used, and deprecated agents. It generates a usage report and recommends cleanup actions to reduce agent catalog bloat.
<Use_When>
- User wants to know which agents are actually being used
- User wants to clean up unused agents from the catalog
- User asks "which agents are unused", "agent stats", "agent cleanup"
- Periodic maintenance to keep the agent catalog lean
</Use_When>
<Do_Not_Use_When>
- User wants to run or delegate to a specific agent -- just delegate directly
- User wants to trace a single session's agent activity -- use
/pepcode:trace instead
- User wants to add a new agent -- modify agent definitions directly
</Do_Not_Use_When>
<Why_This_Exists>
pepcode has 28+ registered agents. Without usage data, it's impossible to know which agents are actively used vs dead weight. This skill provides evidence-based cleanup decisions by reading cumulative usage counters stored in ~/.claude/analytics/agent-usage.json.
</Why_This_Exists>
<Execution_Policy>
- Read global usage data from ~/.claude/analytics/agent-usage.json
- Optionally read project-specific data from ~/.claude/projects/{hash}/analytics/agent-usage.json
- Cross-reference with the registered agent list from src/agents/definitions.ts
- Generate a structured report with tiers: heavy, moderate, light, unused, deprecated
- Suggest cleanup actions for unused and deprecated agents
</Execution_Policy>
1. **Read usage data**: Use the Read tool to read `~/.claude/analytics/agent-usage.json`
2. **Get registered agents**: Read `src/agents/definitions.ts` and extract the full list from `getAgentDefinitions()`
3. **Classify agents into tiers**:
- Heavy use (>20 calls): core agents, do not remove
- Moderate use (5-20 calls): actively used
- Light use (1-4 calls): review for necessity
- Unused (0 calls): candidates for removal
- Deprecated: agents marked `@deprecated` in code
4. **Generate report**: Format as a readable table with columns: Agent, Calls, Last Used, Avg Duration, Model, Status
5. **Recommend actions**:
- Deprecated agents with 0 calls: "Safe to remove"
- Non-deprecated agents with 0 calls after 30+ days of tracking: "Review for removal"
- Agents with declining usage (last 7 days vs previous 30 days): "Usage declining"
6. **Present to user**: Show the report and ask for confirmation before any cleanup
Note: If no usage data exists yet (file not found), inform the user that tracking has just been enabled and they need to use agents for a while before meaningful data appears.
<Tool_Usage>
- Use
Read tool to read ~/.claude/analytics/agent-usage.json
- Use
Read tool to read src/agents/definitions.ts for the registered agent list
- Use
Grep to find @deprecated markers in src/agents/
- Do NOT spawn subagents for this -- it's a direct data-reading task
</Tool_Usage>
User: "agent audit"
Action: Read usage data, cross-reference with registry, output structured report showing executor (87 calls), explore (54 calls), ... product-analyst (0 calls), and recommend removing deprecated stubs.
Why good: Evidence-based, actionable output.
User: "which agents are unused?"
Action: Read usage data, filter to 0-call agents, present list with recommendation.
Why good: Direct answer to the question with data backing.
User: "agent audit"
Action: Just listing all 28 agents alphabetically without usage data.
Why bad: No analytical value without actual usage counts.
<Escalation_And_Stop_Conditions>
- If ~/.claude/analytics/agent-usage.json doesn't exist: Report that tracking is newly enabled, no data yet
- If user confirms removal: Create a task list for the cleanup work and delegate to executor
- Never auto-delete agent files without explicit user confirmation
</Escalation_And_Stop_Conditions>
<Final_Checklist>
Task: {{ARGUMENTS}}