agent-audit

Files (1)

• SKILL.md

SKILL.md (first lines)

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

From leejaedus/pepcode, MIT.

More from leejaedus/pepcode