TL;DR Run
/claude-api prompt-auditfrom your project root, read the report, and apply only the changes you agree with: it won't touch a file on its own. On a test project full of all-caps rules it rewrote almost everything. On my repo of 14 skills it proposed 11 small changes, and the most important one wasn't about style at all: a path that no longer existed.
A tweet from Lance Martin went viral this week (over 200,000 views) recommending /claude-api prompt-audit for Opus 5.5: it checks your skills, your CLAUDE.md and your prompts, and removes the patterns that hold current models back. The command is real and it works. But it doesn't remove anything, and it isn't new: it shipped in v2.1.221. I ran it three times on v2.1.282 with Opus 5.5 to see what it actually does.
What it does
/claude-api is a skill bundled with Claude Code, and prompt-audit is one of its subcommands. When you run it, Claude loads an internal guide (shared/prompt-audit.md, about 39 KB) and works through it in order:
- It inventories everything that reaches the model as text:
CLAUDE.md,SKILL.md, rule files, tool descriptions and, if your code calls the API, the code that builds the requests. - If there's git history, it runs
git blameto see when and why each emphatic line went in. - It puts one question to every instruction: does the model already know this?
- It hands you a report with each finding (
file:line, the exact text, the pattern, why it's dated, and a confidence level) plus a diff with the proposed changes.
The guide is blunt about that last part: propose, never apply without the user's consent. It only edits files when your request explicitly asks it to. Across my three runs it didn't touch a single one (on the repo run I had also taken away its edit tools).
What it flags
| What you have | What it proposes |
|---|---|
CRITICAL: YOU MUST ALWAYS..., IMPORTANT!!! |
The same rule, at normal volume, with its reason |
"Think step by step", <scratchpad>, <thinking> |
Drop it: effort controls how deeply it reasons |
| "Be thorough. Don't stop early." | Drop it: current models already are by default |
| Numbered steps for judgment calls | Describe the goal and how to check it |
| A single sample answer | Drop it, or give several labeled as illustrative |
| Two rules that contradict each other | Rewrite them as one |
The reason, in the guide's own terms: current models follow instructions more literally than the models that text was written for. An all-caps rule meant for a model that ignored it now gets over-applied. And when everything is critical, nothing is.
For Opus 5.5 the guide adds two points by name. Thinking is always on, so a line asking it to think more, or less, no longer controls anything: effort is the only knob. And asking for the reasoning to show up in the answer can trigger a refusal (reasoning_extraction).
What it leaves alone
The guide carries a list of things it won't flag even when they match a pattern. That list is what keeps this from being "make your prompt shorter":
- Context. Your product, your environment, the reason behind a rule. It's the one thing the model can't get anywhere else.
- Exact steps for risky operations. Destructive commands, deploys, auth flows.
- Prohibitions that still earn their place. If the failure still reproduces on the current model, the rule stays.
- A clean file. If it finds nothing, it changes nothing.
What I measured
Three runs with claude -p on Opus 5.5. Cost is total_cost_usd at API list price.
| What I audited | Findings | Changes proposed | Time | Cost |
|---|---|---|---|---|
Test project: one CLAUDE.md and one skill with every bad habit |
8 | 7 | 2 min 14 s | $2.11 |
My skills repo (14 SKILL.md files plus their references) |
16 | 11 | 5 min 39 s | $5.10 |
My global ~/.claude/CLAUDE.md |
5 | 4 | 2 min 22 s | $1.28 |
On the test project it caught everything I'd planted, including the clash between "keep answers under 3 lines" and "explain every change in detail with full reasoning". And it left the one rule with a reason untouched: "never run tests without asking".
My repo came back different. Not one "think step by step", no strings of capitals. The only high-confidence finding was a validation path pointing at a folder that no longer exists: not a style habit, a broken step. The rest were references that had drifted, a rule the very next sentence cancelled, and a "time and tokens are not a constraint" line that pushes Opus 5.5 into over-checking. Every approval gate before publishing stayed where it was.
On the global file, its main proposal was to stop relying on prose for my strictest rules (no commits without my OK) and move them into an ask permission rule in settings.json.
How to use it
1. Run it from the project root.
/claude-api prompt-audit
With no arguments it audits the whole working directory. Your ~/.claude/CLAUDE.md isn't included.
2. Or point it at one file.
/claude-api prompt-audit ~/.claude/CLAUDE.md
Give it a path and that file is the whole scope. In my run it left the project's own CLAUDE.md alone, bad habits and all, and only mentioned it at the end.
3. Read the report before the diff. Its assumptions come first (which model it's targeting and which files are in scope), and findings are sorted by confidence. Low-confidence ones stay in the report and never reach the diff.
4. Apply only what convinces you. The diff arrives as a separate file or inside the report itself, and you pick which parts to apply. It doesn't test the result: without evals every change is a hypothesis, and the report says so and suggests a before-and-after check.
When to run it
Every time you switch models. The guide puts it plainly: prompts are tied to a model, and a line that held something up in one generation is dead weight in the next. If your CLAUDE.md predates Opus 5, Anthropic's tips for Opus 5 already asked you to delete some of it.
Don't mix it up with /doctor, which looks for a bloated CLAUDE.md and lines Claude can already work out from the code. prompt-audit looks for instructions written for a model you no longer use. If your CLAUDE.md is packed with things Claude infers on its own, clean that up first, and if you write skills, Anthropic's 5 rules point the same way.
Official docs: Commands: /claude-api · Skills: bundled skills
Requirements
- Claude Code v2.1.221 or later. Checked on v2.1.282 with Opus 5.5, on September 25, 2026.