cleanup-claude-code

Run the 8-phase Claude Code Hygiene SOP based on Naqeeb Ali-Shamsi's "When Your AI Assistant Becomes a Junk Drawer" playbook (March 2026).

Concrete production results Naqeeb reported after running this SOP:

• 60% more headroom — from 3–4 sessions/day before the rate limit hit to 5–7 sessions/day.
• Startup time 8s → 2s.
• ~5 hours/month of dev time recovered.
• One contributor had 49 plugins installed but only 3 in active use — 46 disabled-but-registered plugins still added startup overhead.

This skill never deletes anything without a backup AND a dry-run preview.

When to invoke

• The user typed /cleanup-claude-code.
• The user complains about slow startup, vanishing session limits, or bloat ("too many plugins", "everything feels slow").
• The user asks to "audit my Claude Code setup", "rationalize my skills", or "decide what to keep".

When NOT to invoke

• Project source-code cleanup → use /simplify.
• Git history cleanup → use /git-clean.
• Resetting Claude Code with no backup — this skill insists on Phase A first.

Dry-run is default

This skill ALWAYS runs in dry-run mode first. Every destructive operation prints what it would do but does not execute until the user explicitly says "apply" or "go ahead". The dry-run preview is the audit; the apply is the cleanup.

The 8 phases

Phase A — Backup ~/.claude/ to a timestamped directory

Before touching anything, snapshot the current state.

Loading code…

The script copies ~/.claude/ recursively (cp -a) to ~/.claude-backups/<YYYYMMDD-HHMMSS>/, preserves permissions and symlinks, and prints the destination path. On Windows it uses robocopy via the Bash environment provided by Git for Windows.

Verify the backup exists and is non-empty before continuing.

Phase B — Health check

Run the four diagnostics:

Collect the output into a single audit report. Note the boot time reported by /doctor — it's the baseline for Phase H.

Phase C — Normalise memory

Open ~/.claude/CLAUDE.md and look for:

• Project-specific instructions that leaked into the global file (e.g. "always use Vite", "deploy to Vercel").
• Stale conventions from old projects.

Move project-specific content into per-project CLAUDE.md files. Use path-scoped frontmatter on skills so they only load for relevant files:

Loading code…

See references/path-scoped-frontmatter.md for the full pattern.

Phase D — Normalise settings + plugins

Inventory every plugin:

• In active use (you ran it in the last 30 days) → KEEP.
• Disabled but installed → UNINSTALL. Disabling alone still loads metadata at startup.
• Duplicates (two plugins owning the same capability) → see Phase G.

Edit ~/.claude/settings.json to remove orphaned entries. Always preview the diff before saving.

Phase E — Normalise hooks

For each hook in ~/.claude/settings.json (and project-scoped settings.local.json), ask:

• Does it enforce a hard rule (deny .env edits, run validators)? → KEEP.
• Is it ornamental — emits a sound, logs a banner, decorates output? → DELETE.

Ornamental hooks consume budget every invocation. Hard-rule hooks are worth their cost. Don't keep "I might want it someday" hooks.

Phase F — Normalise MCP scope

For each registered MCP server, determine:

• User-scope — only set on ~/.claude/settings.json, available globally.
• Project-scope — set in <project>/.claude/settings.local.json, loaded only inside that project.

If an MCP is in user-scope but you only ever use it inside one project, move it to project-scope. This cuts the global startup cost.

Phase G — Capability ownership (Naqeeb's rule)

"Every capability in your setup gets exactly one owner."

See references/ownership-rule.md for the full doctrine.

Make a capability matrix. Example rows:

Label every row with one of: KEEP / DISABLE / UNINSTALL / MERGE / ARCHIVE.

Phase H — Verify with a real project

Re-run /doctor and measure startup time. Try a real workflow you do every day (open a project, run a typical task). Confirm:

• Startup is faster.
• The capability you actually needed still works.
• No skill triggers unexpectedly because of a leftover path-scope.

If anything regressed, restore from the Phase A backup and try again with a smaller change set.

Example reasoning chain

Input

Expected reasoning

1. Confirm Phase A backup is safe to run; execute backup-claude.sh and capture the destination path.
2. Run Phase B diagnostics (/doctor, /memory, /mcp, /config) and present the collected output.
3. Walk Phases C–F in dry-run, showing each proposed change as a diff (no edits applied yet).
4. Build the capability matrix for Phase G; ask the user to confirm each KEEP/DISABLE/UNINSTALL/MERGE/ARCHIVE label.
5. Apply the confirmed changes one phase at a time, with a confirmation between phases.
6. Run Phase H and report the before/after numbers (startup time, plugin count, hook count, MCP count).

Output

Apply mode

When the user says "apply" or "go ahead", proceed phase by phase. Print each change before executing. NEVER batch deletes across phases. After each phase, ask "continue to next phase?" unless the user said "apply all".

References

• references/ownership-rule.md — Naqeeb's "exactly one owner" doctrine.
• references/path-scoped-frontmatter.md — the paths: frontmatter pattern for scoping skills to specific globs.
• scripts/backup-claude.sh — the timestamped backup helper.

Self-lint

This skill was checked with /lint-skill — see public/skills/mcpflix-skills-linter/SKILL.md. To verify:

Loading code…

Expected: all six principles [PASS], exit code 0.