| name | agent-cleaner-skills |
| description | Identify unused Claude Code skills, subagents, and MCP servers and disable them to reduce system-prompt context bloat. Use when the user asks to clean up / slim / 瘦身 their installed skills, subagents, or MCP servers, audit which are unused, or recover context budget. |
agent-cleaner — skills, subagents, and MCP server slimming
When the user wants to slim Claude Code skills, subagents, or MCP servers,
follow the same flow: enumerate → suggest → confirm → disable. The CLI exposes
three parallel command trees: skills, subagents, and mcp.
1. Locate the bundled CLI
The CLI is at ${CLAUDE_PLUGIN_ROOT}/lib/agent-cleaner.mjs. If CLAUDE_PLUGIN_ROOT is unset, compute it as the directory two levels above this SKILL.md. Always invoke via node <abs-path> — never rely on PATH.
2. Listing and suggesting
node "${CLAUDE_PLUGIN_ROOT}/lib/agent-cleaner.mjs" skills suggest --json
The output is a JSON array of suggestions, each with id, name, source, reason (never-used | stale), confidence (high | medium | low), details.
If the user wants to see all skills (not just suggestions), use skills list --json instead.
3. Confirm with the user
Show the suggestion list as a compact table (id + reason + confidence). Never disable without explicit user confirmation. The user may want to keep some "stale" skills.
If the user wants to adjust the staleness threshold, mention they can pass --unused-for=60d (or 2w, 3m, 1y) on the command line, or persist a default in ~/.agent-cleaner/config.json:
{ "unusedForDays": 60 }
4. Disable
Either pass specific ids:
node "${CLAUDE_PLUGIN_ROOT}/lib/agent-cleaner.mjs" skills disable user:lark-mail plugin:foo@bar:thing --yes
Or apply all current suggestions in one shot:
node "${CLAUDE_PLUGIN_ROOT}/lib/agent-cleaner.mjs" skills disable --all-suggested --yes
After disable succeeds, tell the user: "Disabled N skills. Restart Claude Code for the change to take effect — the disabled skill descriptions will no longer appear in your system prompt."
5. Other operations
skills enable <id...> — undo a disable.skills status [--json] — list currently-disabled skills, and detect/auto-reapply any that an upstream plugin upgrade or npx skills update may have restored.skills list --json — full inventory with lastUsed and callCount.
6. Subagents and MCP servers
The same verbs apply with subagents or mcp instead of skills:
node "${CLAUDE_PLUGIN_ROOT}/lib/agent-cleaner.mjs" subagents suggest --json
node "${CLAUDE_PLUGIN_ROOT}/lib/agent-cleaner.mjs" subagents disable subagent:user:reviewer --yes
node "${CLAUDE_PLUGIN_ROOT}/lib/agent-cleaner.mjs" mcp suggest --json
node "${CLAUDE_PLUGIN_ROOT}/lib/agent-cleaner.mjs" mcp disable mcp:user:linear --yes
node "${CLAUDE_PLUGIN_ROOT}/lib/agent-cleaner.mjs" mcp disable --all-suggested --yes
MCP servers are enumerated from ~/.claude.json .mcpServers (user scope) and
each installed plugin's .mcp.json. Usage is detected from
mcp__<server>__<tool> tool calls in transcripts.
Constraints
- Built-in skills cannot be disabled (
init, review, security-review, update-config, etc.). They live inside the Claude Code binary; the CLI will return BuiltinSkillCannotDisableError if you try.
- Disable is reversible. Skills and subagents rename
*.md ↔ *.md.agent-cleaner-disabled; MCP servers are spliced out of their JSON config and the original block is stashed in state. enable reverses both kinds.
- The CLI maintains its own state at
~/.agent-cleaner/state-claude-code.json. Don't edit it by hand.
