/claude-api prompt-audit and /doctor prompt-audit, Tested

Book a Free Strategy Call

Skip the read: talk to Walid in 30 min.

Free strategy call. We map your AI engineering team, you keep the notes.

Claude Code has two prompt audits, and people mix them up. /claude-api prompt-audit reviews the prompts and request code inside an app you built on the Claude API. /doctor prompt-audit (alias /checkup prompt-audit) reviews your Claude Code setup itself: CLAUDE.md, AGENTS.md, skills, subagents and slash commands. Both look for instructions written for older models, and both hand you a report plus a proposed diff instead of rewriting your files.

We ran both on October 24, 2026, on real code: /doctor prompt-audit on the repository behind this website (a Next.js app with a 285-line CLAUDE.md, 17 project skills, 2 subagents and 2 commands), and /claude-api prompt-audit on the Python script behind our Claude Haiku 5.5 benchmark. Every finding quoted below is from those two runs, and we checked each one we discuss against the repo before writing it down.

Quick answer: Use /doctor prompt-audit to clean up your Claude Code instructions and /claude-api prompt-audit <path> to review prompts and request code in a Claude API app. On our repo the first took 7 minutes 24 seconds, cost $4.04 on Claude Opus 5.5 and returned 21 findings, almost all of them stale facts or contradictions between files rather than outdated prompting style. The second took 2 minutes 35 seconds, cost $1.72 and found a parser that was hiding two empty responses in a published benchmark. Neither is a security review.

TL;DR

prompt-audit was added to the bundled claude-api skill in Claude Code 2.1.221. /doctor prompt-audit and /checkup prompt-audit arrived in 2.1.283, which also changed the report so stale paths, stale commands and contradicting instruction files come first.
We ran both on Claude Code 2.1.310 with Claude Opus 5.5, headless (claude -p), with file-editing tools turned off so we could read the report before anything changed.
In our Claude Code config it found a blog-writing skill copied from another site, four skills enforcing a title-length rule the code no longer needs, a CLAUDE.md section pointing agents at pages a past decision ruled out, and two lock-file paths that disagree.
In our API script it found a JSON parser that turned 2 empty Sonnet 5.5 responses into "unparseable" errors, and a temperature parameter that Anthropic's newest API version rejects with a 400.
Every finding we checked by hand was right. The one weak spot: it reads what's in your checkout, so a stale committed file can become its evidence.

What is the difference between /claude-api prompt-audit and /doctor prompt-audit?

They run the same kind of review on different files. The Claude Code changelog describes prompt-audit in the claude-api skill as a check of "prompts and tool descriptions for patterns written for older models" (2.1.221), and /doctor prompt-audit as an audit of "your CLAUDE.md files, skills, agents and commands for prompting patterns written for older models" (2.1.283).

	`/claude-api prompt-audit`	`/doctor prompt-audit`
Added in	Claude Code 2.1.221	Claude Code 2.1.283 (alias `/checkup prompt-audit`)
Reads	System prompts, tool descriptions and request-building code in your app	CLAUDE.md, AGENTS.md, `.claude/skills`, `.claude/agents`, `.claude/commands`
Target model	The model your app calls (it inferred Haiku 5.5 from our script)	The model running your Claude Code session
Typical findings	Format instructions that duplicate structured outputs, brittle parsing, sampling parameters newer API versions reject	Stale paths and commands, files that contradict each other, repeated "MUST" rules, history stories that add no instruction
Output	Report, findings table, proposed diff	Report, findings table, proposed diff
Our run	13 turns, 2 min 35 s, $1.72	63 turns, 7 min 24 s, $4.04

Both reports group findings the same way: Group 1 is dated prompt text, Group 2 is stale or contradicting instruction files, Group 3 is tool descriptions and Group 4 is request configuration. Each finding gets a file and line, the evidence, a confidence level and an action (rewrite, remove, add or flag).

Free weekly brief

Steal our production automations

The exact n8n flows, Claude Code setups, and prompts we ship for clients, broken down step by step. No spam, unsubscribe anytime.

How do you run a Claude Code prompt audit?

Update Claude Code first (claude --version should be 2.1.283 or later for the /doctor form), then run either command from the project root:

# Inside an interactive session
/doctor prompt-audit
/claude-api prompt-audit src/agent/prompts.py

# Headless, the way we ran it, with edits turned off so you get a report only
claude -p "/doctor prompt-audit" --disallowedTools "Edit,Write,NotebookEdit"
claude -p "/claude-api prompt-audit public/benchmarks/jev-vs-haiku-5-5/jev_benchmark.py" \
  --disallowedTools "Edit,Write,NotebookEdit"

Two things we learned from the headless run:

It skips what it can't read. Our report said it did not audit ~/.claude/ (user-level CLAUDE.md, skills, plugins) or parent directories, "because this session couldn't read them": the session asks for approval before reading those paths and couldn't ask in print mode. Run it interactively, or grant read access, if your user-level config matters.
It stays out of secrets on purpose. It skipped .mcp.json, settings files and an MCP config inside a skill folder because "MCP config can hold secrets."

We also ran both audits on a throwaway git worktree, so even an accidental edit couldn't touch the working copy.

What did /doctor prompt-audit find in our Claude Code setup?

The report opened with a verdict we didn't expect: "The prompt text itself is in good shape: little shouting, no 'think step by step' scaffolds, no tricks aimed at older models. Almost every finding is a stale fact or a contradiction between files."

That matches how a Claude Code setup rots. Nobody writes bad prompts on purpose; the code moves and the instructions don't. Of its 21 findings, 19 came with a proposed edit and 2 were flagged for a human decision. These are the ones that mattered most.

A skill written for a different site

Our general-blog-post skill said "Write a high-quality, SEO-optimized blog post for AY Rank", a different site from this one. It described a database table (public.post, snake_case columns) that doesn't exist here, linked to /geo-optimization-london, /#book-audit and /seo-sprint.html, none of which exist on this site, pointed to four reference files that aren't in the folder, capped meta descriptions at 64 characters (sibling skills say 140 to 160), and told writers to use "73% average increase in AI citations" as social proof with no source.

The audit also noticed why this matters: "Four other skills hand blog writing to this skill, and it triggers on 'write a blog post'." We confirmed every point. It's the highest-value finding in the report, because an agent following that skill would publish wrong links and an unsourced claim.

A title-length rule the code no longer needs

Four skills told agents to keep seoTitle at 46 characters or less because the blog "renders seoTitle + ' | AY Automate'". The audit checked the renderer instead of trusting the skill: "app/blog/[slug]/page.tsx:39-43 uses post.seoTitle with no suffix, and no layout defines a title template." The publish script also already reads the short seo_title field first. We looked at both files. The suffix is gone, so agents have been trimming titles 14 characters shorter than they need to be.

Instructions that point at work a past decision cancelled

Our CLAUDE.md still listed a "current planned queue" of tasks 244 to 256 and nine /services/*-agency routes to build. The audit cross-checked the task board and our decision log, and quoted an architecture decision saying not to build those pages because existing /agency/*-dev pages already target the same keywords. Its summary: the section "loads every session and pushes agents toward pages that would compete with the site's own /agency/*-dev pages for the same keywords."

Two lock rules that disagree

CLAUDE.md told agents to create locks in .ay/tracking/locks/ in one section and in .ay/locks/ in another. The audit used git blame to date each passage (May versus June), found which slash commands agree with which path, and then did not pick a winner: "Lock rules are a safety mechanism, so this is flagged, not rewritten. You decide." That restraint is the right call, and it's the behavior you want from a tool that edits agent instructions.

What it flagged about prompting style

Only a few findings were about prompt wording, and they were the kind newer models don't need:

Our listicle skill stated the internal-link rule three times, with "MUST", "hard requirement, not optional" and "mandatory, not optional." The audit's note: "Current models follow a requirement stated once." Its diff keeps the rule and the reason, once.
One skill told a long incident story about a past image mistake after already stating the rule. The proposed edit keeps a one-sentence reason and drops the story.
CLAUDE.md's 65-line "First Contact Protocol" loads every session but only applies to a fresh install. The audit flagged it as low confidence instead of proposing a cut.

The other stale facts

Missing mode files (CLAUDE-PLAN.md and five siblings) that session-start step 6 tells agents to load; an AGENTS.md that was a find-and-replace copy pointing to a .Codex/ folder; a schema instruction that would have added a second FAQPage block to blog posts that already get one; reference files and helper scripts that skills cite but that don't exist; a missing seo_title key in the listicle template; and a skill that still describes where data lived before a refactor. Each came with file, line and the code it checked.

What did /claude-api prompt-audit find in our Claude API script?

We pointed it at the harness behind our Haiku 5.5 benchmark: a Python script that sends 791 labeled decisions to Claude Haiku 4.5, Haiku 5.5 and Sonnet 5.5 through OpenRouter with a strict JSON schema. It started by saying what it would not do: it didn't propose moving the script to the Anthropic SDK, and it told us not to edit the file at all, because it's "the public script that produced the published results.jsonl" and changing it would break the link between script and numbers. The diff, it said, is "meant for the copy you make for the next run."

It found five things:

#	What it found	Our check	Worth applying?
1	`parse_json` strips code fences and slices `{...}` out of free text, inside a broad `except`. With strict JSON-schema output that code never helps, and it recorded 2 empty Sonnet 5.5 replies as `unparseable: 'NoneType' object has no attribute 'strip'`	Correct. Our published analysis shows exactly those 2 failures, and the script never saved `finish_reason`, so we can't say why they were empty	Yes, for the next run
2	"Return JSON only: ..." in the system prompt repeats what the schema already enforces	Correct, but the same sentence is the only place `probability` is defined. The audit spotted that and kept the definition	Next run only, since it changes input tokens and cost
3	`temperature: 0` is still sent to Haiku 4.5	Anthropic's versioning page confirms that under API version `2026-10-21`, "the `temperature`, `top_p`, and `top_k` request parameters are removed. A request that sends any of them returns a 400 error on every model"	Your call. It depends on which API version OpenRouter sends
4	`reasoning: {"effort": "minimal"}` with `max_tokens: 300`	Works today (about 18 output tokens, no failures). It's a flag, not an edit	Watch only
5	The docstring says "temperature 0" for every model, but the code skips it for the two 5.5 models	Correct	Yes, docs fix

Finding 1 is the one that earns the command its place. The audit read the published failure log, traced it back to the parser and pointed out that the 2 "unparseable" rows were really empty responses, then proposed this change:

+    choice = j["choices"][0]
+    content = choice["message"].get("content")
+    if not content:
+        return {"ok": False, "err": "no content, finish_reason=%s" % choice.get("finish_reason"),
+                "latency": dt, "retries": att}
     try:
-        out = parse_json(j["choices"][0]["message"]["content"])
-    except Exception as e:
+        out = json.loads(content)
+    except ValueError as e:

Finding 3 could fail without a crash. As the audit put it, if the provider moves to the new API version, every Haiku 4.5 call "would fail, get logged as ok: false, and be counted as wrong," so the scores would quietly drop instead of the run erroring out.

Which prompt-audit findings were worth applying?

We'd sort them into three buckets:

Bucket	Findings	Why
Apply	The blog skill written for another site, the title-length rule, the stale task queue in CLAUDE.md, missing reference files, the missing `seo_title` key, the parser fix (next run)	Each one would make an agent do the wrong thing today, and each was verified against code
Apply when convenient	Repeated "MUST" rules, the incident narrative, the docstring fix	Harmless today, but they cost tokens every session and make the files harder to keep current
Human decision	The two lock paths, `temperature` on Haiku 4.5, the First Contact section	The audit flagged these instead of fixing them, and it was right to

The one weakness we found: the audit trusts what's in your checkout. For the stale-queue finding it quoted a task board file committed to git, and that copy is older than the live board our agents use. The conclusion still held (the live board marks that work superseded), but if your agents' real state lives outside the repo, check the evidence before you apply a hunk.

Is prompt-audit a security audit?

No. It doesn't test prompt injection, check which tools an agent can reach, scan for secrets or vet third-party skills and MCP servers. It actually avoids reading MCP config because it might contain secrets. Use it to keep instructions current when you change models. For what your agents can touch, see our Claude Code security audit checklist or the Claude Code security audit service.

When should you run it?

After a model upgrade. Moving an app to Claude Sonnet 5.5 or Opus 5.5 is where old format instructions, sampling parameters and parsing workarounds start to break, which is what the API audit looks for.
When agents start doing odd things. On our repo, every high-confidence finding was an instruction that disagreed with the code. If agents keep following a rule that seems wrong, that's often why.
Before handing a repo to a new team or agent fleet. A CLAUDE.md collects decisions over months, and the audit is a fast way to find which ones are no longer true.

If you'd rather have someone else run it, fix the findings and set up the guardrails around it, our Claude Code development team does that as part of Claude Code rollouts.

FAQ

What does /claude-api prompt-audit do?

It reviews the prompts, tool descriptions and request-building code in an app that calls the Claude API, looking for patterns written for older Claude models: format instructions that structured outputs make redundant, brittle parsing, removed sampling parameters and thinking settings sized for another model. It returns a findings table and a proposed diff. It shipped in Claude Code 2.1.221 as a subcommand of the bundled claude-api skill.

What does /doctor prompt-audit check?

It audits your Claude Code configuration: CLAUDE.md, AGENTS.md, CLAUDE.local.md, skills, subagents, slash commands, rules and output styles. On our repo it reported stale paths, references to files that don't exist, contradictions between skills and repeated pressure language. /checkup prompt-audit is the same command. It shipped in Claude Code 2.1.283.

Does prompt-audit change my files?

It proposes a diff and asks you to confirm each hunk. Its report said Group 2 edits "are proposals for you to confirm," and that none "should be applied as a blanket cleanup." We ran it with editing tools disabled so we could read the report first, which we recommend for a first run.

How much does a Claude Code prompt audit cost?

It uses your normal Claude Code usage. Our runs on Claude Opus 5.5 cost $4.04 for /doctor prompt-audit on a repo with 17 skills, 2 subagents and a 285-line CLAUDE.md (63 turns), and $1.72 for /claude-api prompt-audit on one 338-line Python file (13 turns). Smaller configs will cost less.

Does prompt-audit work on apps that use OpenRouter or another gateway?

Yes, with caveats. Our script calls Claude through OpenRouter, and the audit still reviewed the prompts and request code. It marked findings that depend on how the gateway translates requests as lower confidence, because it can't see that translation.

Why didn't prompt-audit read my ~/.claude folder?

In a headless run (claude -p) the session can't ask for approval to read paths outside the project, so it skips user-level CLAUDE.md, skills and plugins and says so in the report. Run it in an interactive session, or allow those reads, to include them.

Is prompt-audit the same as a security audit?

No. It checks whether instructions are current, not whether agents are safe. It doesn't test prompt injection, tool permissions, secret exposure or the skill and MCP supply chain. See what a Claude Code security audit covers.

Sources: our own runs of /doctor prompt-audit and /claude-api prompt-audit with Claude Code 2.1.310 and Claude Opus 5.5, October 24, 2026, 05:55 to 06:03 UTC; Claude Code changelog (versions 2.1.221 and 2.1.283); Anthropic API versions, read October 24, 2026; the Jev vs Claude Haiku 5.5 benchmark files.