agent-cleaner-skills

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.