agent-audit

<Purpose> 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. </Purpose>

<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>

<Steps> 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. </Steps>

<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>

<Examples> <Good> 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. </Good> <Good> 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. </Good> <Bad> User: "agent audit" Action: Just listing all 28 agents alphabetically without usage data. Why bad: No analytical value without actual usage counts. </Bad> </Examples>

<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>

• Usage data was read successfully (or absence was reported)
• All registered agents are accounted for in the report
• Deprecated agents are identified from code markers
• Recommendations are evidence-based (not guesses)
• No agent files are modified without user confirmation </Final_Checklist>

Task: {{ARGUMENTS}}