---
name: legendtkl/agent-cleaner-skills
source: https://app.decimal.ai/s/legendtkl-agent-cleaner-skills@2/SKILL.md
source_sha256: 4bd576a73b49
---

# agent-cleaner — Codex skills and MCP server slimming

When the user wants to slim Codex skills or MCP servers, follow the same
flow: enumerate → suggest → confirm → disable. The CLI exposes parallel
`skills` and `mcp` command trees on Codex (subagents are Claude Code-only).

## 1. Locate the bundled CLI

Prefer `${AGENT_CLEANER_CLI}` if set. Otherwise locate the newest installed bundle:

```bash
find "${CODEX_HOME:-$HOME/.codex}/plugins/cache/local/agent-cleaner" -path '*/lib/agent-cleaner.mjs' -type f 2>/dev/null | sort | tail -1
```

If that finds nothing, check the current repository path:

```bash
test -f plugins/codex/lib/agent-cleaner.mjs && pwd
```

Always invoke via `node <abs-path>` and always pass `--host=codex`.

## 2. Listing and suggesting

```bash
node "<abs-path>/agent-cleaner.mjs" --host=codex 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, use `skills list --json`.

## 3. Confirm with the user

Show the suggestion list as a compact table with id, reason, and confidence. Never disable without explicit user confirmation.

If the user wants to adjust the staleness threshold, mention `--unused-for=60d` (or `2w`, `3m`, `1y`) or persist a default in `~/.agent-cleaner/config.json`:

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

## 4. Disable

Either pass specific ids:

```bash
node "<abs-path>/agent-cleaner.mjs" --host=codex skills disable user:codex:lark-mail plugin:gmail@openai-curated:gmail --yes
```

Or apply all current suggestions in one shot:

```bash
node "<abs-path>/agent-cleaner.mjs" --host=codex skills disable --all-suggested --yes
```

After disable succeeds, tell the user: "Disabled N skills. Restart Codex or start a new Codex session for the change to take effect."

## 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 or skill update may have restored.
- `skills list --json` — full inventory with `lastUsed` and `callCount`.

## 6. MCP servers

The same verbs apply with `mcp` instead of `skills`. Codex MCP servers live as
`[mcp_servers.NAME]` blocks in `~/.codex/config.toml`:

```bash
node "<abs-path>/agent-cleaner.mjs" --host=codex mcp suggest --json
node "<abs-path>/agent-cleaner.mjs" --host=codex mcp disable mcp:user:codex:linear --yes
node "<abs-path>/agent-cleaner.mjs" --host=codex mcp disable --all-suggested --yes
```

Usage is detected from `mcp__<server>__<tool>` tool calls in Codex session
transcripts under `~/.codex/sessions/`.

## Constraints

- Codex system skills under `~/.codex/skills/.system` cannot be disabled.
- Skills disable: `mv SKILL.md SKILL.md.agent-cleaner-disabled`. MCP disable:
  the `[mcp_servers.NAME]` block is spliced out of `config.toml` and the
  original lines are stashed in state. `enable` reverses both.
- State is kept at `~/.agent-cleaner/state-codex.json`.