What /checkup cleans up, and what it leaves behind

/checkup is /doctor under another name — the same command, registered with two. It runs nine checks over local data only, reads your usage counters and your recent session transcripts, and comes back with a report and at most two confirmation questions. The headline most coverage gets wrong: it does not delete your skills. It switches them off in settings, which is one edit to undo. What it leaves behind is a moment in time, not a list you can keep.

It is the same command as /doctor

Typing /checkup and typing /doctor in a session run identical work: checkup is registered as an alias. Neither is the same as the terminal command claude doctor, which is the read-only half — it prints installation diagnostics and fixes nothing. The slash version can propose and apply changes, and asks before it does.

/checkup            # in a session — the full nine checks, proposes fixes
/doctor             # exactly the same command

claude doctor       # in the terminal — diagnostics only, changes nothing

The order it works in is fixed: every check runs read-only first and you get the whole report, then it asks at most two questions — one covering the cleanup, one covering the permission changes, because those widen what runs without asking you.

The nine checks, in one list

Cleanup of unused extensions is one check out of nine. Most of the command is about your memory files and your context budget, which is worth knowing before you run it expecting a skills report.

• Installation health: duplicate or leftover installs, PATH problems, settings files that fail to parse, agent definitions that never load, skill frontmatter that fails to parse.
• Unused skills, MCP servers and plugins, weighed against what each costs in context.
• Duplication between your local CLAUDE.md files and the ones checked into the repository.
• Content in checked-in CLAUDE.md files that a session could work out for itself — directory layouts, dependency lists — and could therefore lose.
• Always-loaded guidance that would be better as a lazily loaded skill or a nested CLAUDE.md.
• Slow hooks, measured from the durations recorded in your transcripts.
• Context-heavy extensions, ranked by estimated always-resident tokens.
• Whether your Claude Code is the latest for its release channel — the one check that touches the network.
• Two permission proposals: making auto mode your default, and pre-approving read-only commands you keep denying.

It disables, it does not delete

This is the part the announcement-week write-ups got wrong. Nothing is removed from ~/.claude/skills. A skill it agrees with you about is turned off by an entry in a settings file, and the folder stays exactly where it was.

// a personal skill, in ~/.claude/settings.json
"skillOverrides": { "some-skill": "off" }

// a plugin, in the settings file that wins for its scope
"enabledPlugins": { "some-plugin@some-marketplace": false }

// an MCP server — a command, not a file edit
/mcp disable some-server

Scope is deliberate too: those edits go to user and local files only, never to anything checked into the repository. The one exception is the CLAUDE.md checks, which may propose changes to committed files — and quote every removal so you can judge it and put it back.

What it leaves behind

A report in your terminal, and settings edits it lists file by file at the end. There is no artefact: nothing is written to disk that you can open next month and compare against. Run it again in December and you get a fresh reading with no memory of this one.

• The window is roughly the fifty most recently modified session transcripts. A skill you use monthly can fall outside it and read as unused; the command says which window it covered, so read that line before agreeing to anything.
• usageCount from ~/.claude.json is a lifetime total, so a heavily used skill that you dropped in March still looks busy. Recency comes from lastUsedAt and the transcripts, not from the count.
• Passive things have no usage signal at all. A plugin whose payload is a theme or an output style never increments a counter, and its zero means nothing was logged rather than nothing was used.
• Token figures are estimates, roughly characters divided by four, and the command labels them that way.
• MCP tool schemas are deferred behind Tool Search by default now, so an idle MCP server usually costs far less context than the older advice assumed.

Run it. It is free, it is thorough, it is reversible, and it is the fastest way to find dead weight you had forgotten about. The thing it is not is a place to look. That is the honest difference between a cleanup prompt and an inventory: /checkup is something you do occasionally, and Loadout is a window you open — the same skills, MCP servers, subagents and commands listed with their counts, whether or not you are in the mood for a tidy-up. If a one-shot cleanup is all you want, the command already does it, and you do not need us for that.

Questions

Does /checkup delete unused skills?

No. It disables them by writing a skillOverrides entry set to "off" in your settings file, and plugins by setting them to false in enabledPlugins. The skill folders stay on disk, so undoing it is one edit — or one more request in the same session.

What is the difference between /checkup, /doctor and claude doctor?

/checkup and /doctor are the same command: checkup is a registered alias. The terminal command claude doctor is the read-only subset — it prints installation diagnostics and changes nothing, and the in-session version repeats those checks and adds eight more.

How does /checkup decide a skill is unused?

It reads the usage counters in ~/.claude.json and scans roughly the fifty most recently modified session transcripts across every project you have opened. A skill with no counter entry and no transcript hits in that window is what it proposes to switch off.