# Agent Cleaner Skills

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

- Skill: `legendtkl/agent-cleaner-skills-2` (Agent Skill)
- Install (CLI): `npx skillmds@latest add legendtkl/agent-cleaner-skills-2`
- Raw SKILL.md: https://api.skillmd.com/api/skills/legendtkl/agent-cleaner-skills-2/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: legendtkl (https://skillmd.com/u/legendtkl)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/legendtkl/agent-cleaner-skills-2

---


# 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

```bash
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`:

```json
{ "unusedForDays": 60 }
```

## 4. Disable

Either pass specific ids:

```bash
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:

```bash
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`:

```bash
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.