Feature request: evaluate and score user-created subagents and skills with keep/remove recommendations
Summary
Add a built-in Claude Code command (e.g., /audit-subagents, /audit-skills, or a unified /audit-extensions) that analyzes the user's custom subagents (.claude/agents/*.md) and skills (.claude/skills/*/SKILL.md), scores each one on value contribution, and recommends whether to keep, revise, or remove them. Surface the same analysis as a dedicated section in the HTML report produced by /insights.
Problem
Power users accumulate dozens of custom subagents and skills over time. In practice:
- Many are created once for a narrow task and never used again.
- Some overlap heavily with each other or with built-in capabilities.
- Some have drifted out of sync with the project (referencing files/paths that no longer exist, or describing behavior the codebase has moved past).
- Descriptions are often too vague for the dispatcher to match against — so the skill/agent silently never fires.
- There's no principled way to decide which ones to prune, short of manual review.
The result is cruft: longer context, worse dispatch precision (more candidate skills/agents diluting the match), and higher cognitive load when writing new ones.
Proposed behavior
A command that, for each custom subagent and skill:
- Usage signal — count how often it has been invoked (from transcripts / session logs) over a user-specified window.
- Description quality score — check whether the description is specific enough to fire reliably (trigger keywords, SKIP clauses, concrete examples) vs. vague.
- Overlap detection — cluster items with substantially similar descriptions/triggers and flag redundancy.
- Staleness check — detect references to files, paths, tools, or commands that no longer exist in the repo.
- Value rating — a composite score (e.g., 0–10) with a one-line justification.
- Recommendation —
KEEP/REVISE/REMOVE, with the reason and, forREVISE, a suggested edit.
Output as a ranked table so the user can quickly sweep through and approve removals in bulk.
/insights integration
Add a new section to the HTML report generated by /insights titled e.g. "Custom Extensions Health" that renders the same audit data in a browser-friendly format:
- Summary tiles at the top: total custom subagents, total custom skills, count flagged
REMOVE, count flaggedREVISE, count unused in the reporting window. - Sortable / filterable table with one row per subagent and skill, columns: name, type (agent/skill), scope (user/project/plugin), invocations in window, description-quality score, overlap group, staleness flags, composite value score, recommendation, and expandable justification.
- Visual cues: red row for
REMOVE, yellow forREVISE, green forKEEP; a small bar or sparkline showing invocation counts over time. - A "suggested revisions" drawer per row showing the rewritten description/trigger text, copy-to-clipboard for quick application.
- Link at the top of the section pointing to the raw
/audit-extensionscommand so users can re-run interactively.
This keeps the audit discoverable for users who already run /insights periodically, without requiring them to remember a separate command.
Why this belongs in Claude Code
Only Claude Code has visibility into both the definitions and the actual invocation history. A user can't easily compute "this skill has fired 0 times in 90 days" without building their own tooling on top of transcripts.
Nice-to-haves
- Dry-run vs. apply mode (with
--applyactually deleting or rewriting files after confirmation). - Per-scope filtering (
--user,--project,--plugin). - Export as JSON for scripting.
- CLI flag on
/insights(e.g.,--skip-extensions-audit) for users who don't want this section.
This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗