Opus 5.5 Prompt Audit: What to Keep in Your CLAUDE.md, Not Just What to Cut

2026-09-23
Brian

· Updated
Subscribe
Get New Posts by Email
New RepoSquare posts in your inbox: comparisons, setup guides and explainers on open-source tools and AI coding agents. No spam, and you can unsubscribe anytime.

On launch day for Claude Opus 5.5, Anthropic’s Lance Martin posted a one-line tip: run /claude-api prompt-audit before you touch the effort dial. Most of the advice that followed was about what to delete from CLAUDE.md. The audit file itself spends just as much space on what you must not delete, and that half is where people get burned.

I read the current skill file in Anthropic’s public skills repo, ran a crude pre-check on three well-known public instruction files, and wrote down what the audit would keep. The short version is that a good audit changes less than you’d expect.

Why Opus 5.5 Punishes Old Prompt Habits

Opus 5.5 thinks before every reply, and thinking can’t be turned off. Lines like “think step by step” or “verify every file twice” don’t nudge it anymore, they add a second pass on top of the first. Anthropic’s default effort for the model is medium, and its own coding evals show 5.5 at medium matching or beating Opus 5 at high.

Anthropic measured the cost of carrying old rituals forward. On a 44-ticket support benchmark, moving from Opus 4.8 to Opus 5.5 at low effort cut cost about 18 percent, and running the prompt audit on top cut another 9 percent with the same tasks. That second number is the one you control, and it needs no new settings.

Five steps in order: grep for signals, run /claude-api prompt-audit, keep what only you know, re-run one familiar task, raise effort only if medium stalls

Inside the Skill File: Four Groups and Two Deliverables

The procedure lives at skills/claude-api/shared/prompt-audit.md in the anthropics/skills repo. When I cloned it on 18 November 2026 the file was 238 lines long, and its first instruction tells the agent to carry out the steps rather than summarize them. Every run has to produce two things: a report where each finding has a file:line, a named pattern, a reason and a confidence level, and a proposed diff that’s never applied without your consent.

The scan works through four groups.

GroupWhat it looks for
1. Dated prompt textCaps-lock pressure, hedges like “try to”, step-by-step scaffolds, scratchpad tags, prohibition clusters
2. Brittle skill and config filesRules from one bad session, hardcoded paths and versions, files that contradict each other
3. Tool descriptionsShouting in descriptions, overlapping tools, behavior hidden in a description
4. Request configDeprecated fields, cache-hostile ordering, duplicate subagents

Group 2 is broader now than the launch-week summaries suggest. It asks the agent to check that each path named in an instruction file still exists in the repo, and that each command and flag is still defined, by reading files rather than running anything. A claim the repo contradicts is a high-confidence finding. That’s the part that catches a CLAUDE.md still pointing at a folder you renamed in spring.

The Keep List Most Summaries Skip

The skill has a section called “What not to flag”, and it’s as binding as the pattern tables. It opens with a warning that an audit which only says delete hurts the people who follow it most carefully. The rules I’d tape to the monitor are these.

  1. Context is never cruft. Audience, environment facts, quality bar and the reasons behind constraints stay.
  2. Length alone isn’t a reason to cut anything.
  3. Fragile operations keep exact scripts, such as destructive commands, auth flows and compliance steps.
  4. A prohibition against a failure that still happens on this model stays.
  5. Duplicated text that agrees and works isn’t cruft. Only copies that disagree get merged.
  6. Sometimes the fix is to add guidance for the new model, not remove it.

It also says plainly that an audit which finds nothing should change nothing. An empty diff is a valid result.

What a Quick Grep Found in Three Public Files

Before running the real audit, I wanted to see how noisy the obvious signals are. I wrote a short script that greps for the Group 1 signals the skill lists: capitalized MUST, NEVER, ALWAYS, CRITICAL and IMPORTANT, step-by-step and scratchpad scaffolds, verify-twice rituals, hedges and identity stubs.

#!/usr/bin/env bash
# Crude pre-pass for prompt-audit Group 1 signals. Finds candidates, decides nothing.
for f in "$@"; do
  echo "== $f ($(wc -l <"$f") lines)"
  grep -nE '\b(MUST|NEVER|ALWAYS|CRITICAL|IMPORTANT)\b' "$f" | sed 's/^/  pressure  /'
  grep -niE 'step[- ]by[- ]step|scratchpad|<thinking>|think (carefully|hard)' "$f" | sed 's/^/  scaffold  /'
  grep -niE 'double[- ]check|verify (twice|again)|be (very |maximally )?thorough' "$f" | sed 's/^/  ritual    /'
  grep -niE '\b(try to|if possible)\b' "$f" | sed 's/^/  hedge     /'
  grep -niE '^(reminder:|you are (a|an) )' "$f" | sed 's/^/  stub      /'
done

I pointed it at the Karpathy-inspired CLAUDE.md from forrestchang/andrej-karpathy-skills, the CLAUDE.md in anthropics/claude-code-action, and VS Code’s .github/copilot-instructions.md.

== forrestchang_andrej-karpathy-skills.md (65 lines)
== anthropics_claude-code-action.md (58 lines)
== microsoft_vscode.md (178 lines)
  pressure  158:- You MUST deal with disposables by registering them immediately after creation ...
  pressure  159:- You MUST NOT use storage keys of another component only to make changes to ...
  pressure  163:- Service dependencies MUST be declared in constructors and MUST NOT be accessed ...

I expected a pile of hits. Two files came back clean, and the three VS Code lines are real architecture rules, not anxiety. Under the keep list they stay. The skill’s fix for pressure language is to say the same rule at normal volume with its reason, so the most an audit should propose is “Register disposables right after creation, because…” in place of the capitals. A grep can tell you where to look, but it can’t make that call, which is why the skill exists.

Run It on Your Own Repo

You’ll need Claude Code with the claude-api skill installed from Anthropic’s official skills marketplace. Work in the repo you actually use, not a toy folder.

/model claude-opus-5-5
/effort medium
/claude-api prompt-audit

Before the audit, run one short task you already trust, like a single bug fix, and note the turns and output tokens from /usage. Then read the report line by line. Accept the hunks you can defend, leave anything you can’t, and run the same task again. If quality drops, put back one rule at a time in its shortest form. The skill’s own last step says removal is a hypothesis to test, not a conclusion.

If your file is ignored rather than overused, that’s a different problem, and Claude Code not reading AGENTS.md walks through those fixes. For how the files load in the first place, the learn-claude-code walkthrough is still the clearest map.

When Raising Effort Is Worth It

Only after the prompt is clean, and only when medium stalls on a real multi-file problem. The launch-night tables people posted on r/ClaudeAI put Terminal-Bench at 57.6 percent for $2.94 at medium, 64.2 percent for $3.88 at high and 66.4 percent for $7.35 at xhigh. High was the last step that clearly paid. On FrontierCode, medium was the peak. These are community numbers, not mine, but they point the same way as Anthropic’s advice to start at medium.

Changing effort mid-session also clears the prompt cache, because effort sits in the cached prefix. Pick one level per task and leave it.

A clean CLAUDE.md after all this is usually dull: how the repo is laid out, what done means, what’s destructive, when to stop and ask. The Karpathy-style four rules fit there when they’re written as constraints. A long SKILL.md is still fine when it teaches a tool the model doesn’t know, the way OfficeCLI’s skill does. And if your agent keeps adding layers you didn’t ask for, whether Ponytail stops Claude Code over-engineering covers that habit.

The honest limit here is that I haven’t run the audit inside Claude Code on a private repo of my own, so I can’t tell you what percentage it’ll save you. What I can say is that the skill is built to leave well-written files alone, and two of the three public files I checked were already clean.

Get New Posts by Email
New RepoSquare posts in your inbox: comparisons, setup guides and explainers on open-source tools and AI coding agents. No spam, and you can unsubscribe anytime.

2 comments

Leave a comment