Claude Code Added /doctor prompt-audit. It's a Different Command Than /claude-api prompt-audit (2026)

Claude Code’s v2.1.283 release, shipped September 25, 2026, added /doctor prompt-audit (alias /checkup prompt-audit) to “audit your CLAUDE.md files, skills, agents and commands for prompting patterns written for older models.” That is a genuinely new command, not a rename — Claude Code already had a subcommand called prompt-audit, and it does something else. It lives under /claude-api, it’s been there since v2.1.221 (shipped August 4, 2026), and it audits your application’s Claude API prompts, not your Claude Code setup. Two commands, same name, different targets, six weeks apart. Here’s what actually distinguishes them, and what we found running the underlying pattern-check against 325 real CLAUDE.md and rule files.

Two prompt-audit commands, not one

The official commands reference currently documents /claude-api’s version like this:

Run prompt-audit to flag instructions written for older models in your prompts, skills, and tool descriptions and propose fixes as a diff.

That’s scoped to code that imports anthropic or @anthropic-ai/sdk — it’s part of a bundled skill meant for developers building products on the Claude API, alongside sibling subcommands like migrate (move existing API code to a newer model) and cost-optimize (profile token spend). If your repo has no SDK usage, /claude-api never activates, and its prompt-audit isn’t touching your CLAUDE.md at all.

The new one is different in scope and in what triggered it. From the v2.1.283 release notes:

Added /doctor prompt-audit (also /checkup prompt-audit) to audit your CLAUDE.md files, skills, agents and commands for prompting patterns written for older models

A second line in the same release refines it further:

Improved prompt-audit on Claude Code configuration: stale paths, stale commands and contradicting instruction files now lead the report, and thinking keywords that Claude Code documents are kept

That second bullet is worth sitting with. It means the audit isn’t a blunt keyword scanner that flags every all-caps word — it’s aware that Claude Code’s own docs define certain trigger phrases (the “think” / “think hard” / “ultrathink” family that scales thinking budget) as functional, not stylistic noise, and it’s told not to flag those. It also means the report is prioritized: broken references (stale paths, stale commands) and internally contradicting instructions surface before generic phrasing complaints.

As of this writing, the main /doctor entry on the commands reference page hasn’t been updated to list prompt-audit as a subcommand yet, and Anthropic’s weekly “What’s new” digest tops out at Week 37 (September 7–11) — a week and a half before v2.1.283 shipped. The feature exists and works; the docs just haven’t caught up. That’s not unusual for a fast-moving CLI, but it means running /doctor prompt-audit yourself right now is the only way to see its actual output, since there’s no worked example in the official docs to check against yet.

What “prompting patterns written for older models” means in practice

Neither release note enumerates the exact pattern list /doctor prompt-audit checks against. But the underlying problem it’s aimed at is well documented elsewhere: instruction styles that made sense for GPT-3.5-era or early-Claude prompting — heavy role-play framing (“You are an expert…”), repeated emphasis words in all caps, and blanket imperatives — do less for current models, which follow structured, concrete instructions without needing to be told the same thing three times in three different typefaces of urgency.

We didn’t want to guess at how common that stuff actually is, so we ran a pattern check against our own gallery — 325 real CLAUDE.md, .cursorrules, and AGENTS.md files pulled from public repositories, not synthetic examples. Here’s what showed up:

“You are an expert in X” is the single most common phrase in the set — one in eight files opens with it. It shows up in community .cursorrules submissions and in maintained project files alike; awesome-cursorrules’ Python FastAPI template and its SvelteKit + TypeScript template both lead with it.

The all-caps emphasis words are less universal but still frequent enough that a scanner flagging them would touch real, currently-maintained repos, not just abandoned examples. MUST and CRITICAL both appear in LangChain’s CLAUDE.md and in spec-kit’s AGENTS.md from GitHub’s own org. bun’s AGENTS.md — a Zig/C++/TypeScript runtime with an actively maintained agent-instructions file — uses CRITICAL. llama.cpp and langflow both use IMPORTANT in their current AGENTS.md files. None of these are throwaway repos; they’re widely-used projects with rule files that get edited alongside the code.

That’s the gap /doctor prompt-audit is stepping into: not “toy examples do this,” but “actively maintained, popular repos still write instructions this way, because nobody goes back and asks whether last year’s phrasing still earns its place.”

What it probably won’t flag

Two categories are worth calling out because they look similar to the patterns above but aren’t the same thing:

• Thinking-budget triggers. Phrases like think, think hard, or ultrathink look like the same over-emphasis pattern as CRITICAL or ALWAYS, but Claude Code’s own docs define them as functional controls over extended-thinking depth. The v2.1.283 note explicitly says these are “kept” — the audit is built to tell the difference between a keyword that does something and a keyword that’s just decoration.
• Genuinely scoped emphasis. A CRITICAL or MUST attached to one specific, narrow instruction (“MUST run npm run typecheck before committing”) is doing real work — it’s not the same failure mode as a CLAUDE.md that opens every third line with ALWAYS and NEVER regardless of stakes. A pattern-frequency count like ours can’t tell those apart; a report that reads the surrounding context, which is what /doctor prompt-audit is positioned to do, can.

Running it yourself

/doctor prompt-audit

or, using the alias:

/checkup prompt-audit

Per the general /doctor behavior documented for the base command, expect a report-first flow: findings surface, and nothing in CLAUDE.md, a skill, an agent definition, or a command file changes until you confirm the fix. That matches how the rest of /doctor’s fix-it behavior works — it’s not a silent auto-rewriter.

Both prompt-audit subcommands are version-gated, so check claude --version before assuming either is available:

• /claude-api prompt-audit requires v2.1.221 or later
• /doctor prompt-audit requires v2.1.283 or later

If you’re only current with your monthly release channel rather than tracking every point release, you may have the older one and not the newer one yet.

A starting checklist for your own CLAUDE.md

• Search your own CLAUDE.md, skills, and agent files for you are an expert, NEVER, MUST, ALWAYS, CRITICAL, and IMPORTANT before you run the audit, so you have a baseline to compare its report against.
• Don’t strip every instance on sight — check whether the emphasis is attached to something specific and consequential (a real failure mode you’ve hit before) versus generic throat-clearing.
• If you maintain both a CLAUDE.md and an SDK-based application in the same repo, expect /doctor prompt-audit and /claude-api prompt-audit to both be available and to report on different files — running one doesn’t cover the other.
• Re-run the audit after a big CLAUDE.md rewrite, not just once. Instruction files accrete the same over-emphasized language over time as new contributors add rules the same way the existing ones read.

You can browse the real CLAUDE.md, .cursorrules, and AGENTS.md files referenced above — LangChain, bun, spec-kit, llama.cpp, and 320+ others — in our gallery.

Related Articles

• Claude Code /doctor (/checkup): The Full Setup Checkup Command Guide
• Writing Effective CLAUDE.md Files: From Blank Page to Production-Ready 2026
• How to Write Claude Code Skills: Complete Developer Guide (2026)
• Claude Code’s allowed-tools Field Doesn’t Restrict Tool Access. An Open Bug Also Lets a SKILL.md Documentation Example Run for Real (2026)