What /checkup cleans up, and what it leaves behind

/checkup is an alias of /doctor, the bundled setup review in Claude Code. It reports configuration problems and proposes changes for you to approve. It is prompt-based work in a Claude session, not a purely local offline scanner. For a focused skill usage report, use /skill-doctor on supported versions.

By Miguel Silva · Updated 2026-09-12

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: setup review and proposed fixes
/doctor             # exactly the same command

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

The current documentation says it reports findings and asks before changing anything. Read the proposed configuration edits separately from permission changes, which affect what future sessions can do without prompting.

What the setup review checks

The original 2.1.233 review covered the categories below. The current /doctor command still reviews setup and context costs, but its prompt can change. Use /skill-doctor if you are 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.

Review cleanup before applying it

The original 2.1.233 prompt used reversible settings to turn off unused skills. Nothing is removed from ~/.claude/skills by that visibility change. Current /doctor is prompt-based, so review its proposed edits rather than assuming any cleanup is incapable of deleting files.

// 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: open the panel and turn it off there
/mcp

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

Keep the report and review the settings diff if you want to compare later. Do not assume a prompt-based check uses an unchanging checklist or transcript window across releases.

• The 2.1.233 prompt inspected for the original guide sampled roughly fifty recent transcripts. Treat that as a version-specific observation, not a current guaranteed window.
• Retained aggregate counters can be historical. Check the most recent recorded use and available transcripts before deciding a skill is obsolete.
• 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.

Use /checkup when you want a broader review, and /skill-doctor when you want the built-in usage report. Loadout provides a separate Mac inventory and editor. Whichever you use, check the history available before treating an item as unused.

Questions

Does /checkup delete unused skills?

The 2.1.233 cleanup inspected for this guide used off settings and kept skill folders. Current /doctor can propose and apply changes, so inspect its plan. If you only want to turn a skill off, use /skills or its visibility setting.

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 examines recorded usage and configuration cost. The original 2.1.233 inspection found counters and a sample of recent transcripts; the exact prompt and window can change. Missing evidence is not proof that an item has no value.