Your Claude Code skills were written for a different model

If you built a Claude Code workflow around skills last year, some of those skills are probably making your agent worse today. Not because you wrote them badly, but because you wrote them for a model you no longer use. This post shows what that drift looks like and the command I now run to catch it: /claude-api prompt-audit.

My teams have used Claude Code and OpenAI Codex every day since early 2025, on legacy maintenance and on a few agent-first systems. We've been through several model upgrades with the same set of skills, and the skills didn't upgrade themselves. When we finally ran the audit on one of our front ends, its CLAUDE.md went from 274 lines to 44.

Skills, plugins and CLAUDE.md are your harness

A few quick definitions, in case you haven't set these up yet.

A skill is a folder with a SKILL.md file in it. The top of the file is a short description that tells Claude when to use the skill. The rest is instructions: how to plan a feature, how to review a diff, how to chase down a flaky test.

A plugin bundles skills, slash commands, subagents and hooks so a whole team can install the same set with one command.

CLAUDE.md is a file in your repository that the agent reads at the start of every session. Codex and several other agents read AGENTS.md for the same job.

Together these are a harness. They decide how the agent plans, how it reviews, what it checks before it calls something done. Most teams I talk to end up with some version of /plan, /review and /debug, plus a CLAUDE.md full of house rules.

They work. That's the problem: once they work, nobody touches them again.

Every skill is tuned to a model, whether you meant it or not

When you write a skill, you test it against the model you have that week. If the model skips the tests, you add "IMPORTANT: always run the tests." If it rambles, you add "Keep it under 100 words." Each of those lines is a patch for one model's habits.

Then a new model ships, and its habits are different. Anthropic's own guidance says current Claude models follow instructions more closely and more literally than the models a lot of this text was written for. So a patch for a weakness the new model doesn't have doesn't just sit there harmlessly. The new model obeys it.

The shouting that once got a lazy model to use a tool now makes an eager one reach for it when it shouldn't. The word cap that stopped an old model from rambling now cuts a careful one off mid-thought. And nobody owns removing these lines, so a skill slowly collects the mitigations for every model it has ever run on.

What drift looks like

Here are the patterns that show up most. Each one was a reasonable fix when someone wrote it.

Shouting. A line like this was written for a model that under-used the linter:

CRITICAL: You MUST run the linter before EVERY change.

A current model takes it at face value, so expect it to run the linter even on a one-word typo fix in a README. When five rules in a file are all marked critical, the markers stop meaning anything. Say it plainly and give the reason: "Run the linter before committing, because CI rejects lint errors."

Steering the thinking with prose. "Think step by step" and "don't overthink this" were ways to control reasoning before models had a dial for it. On Claude Opus 5.5 thinking is always on, and the effort setting is what controls how much it thinks. On Claude Sonnet 5.5, asking it in prose to think less has almost no effect from medium effort up. Delete the line and set the effort instead.

Telling it to stay quiet. Rules like this were written for chatty models:

Don't narrate. Hold all findings until the final summary.

Current models already say less between steps. With this rule in place, your agent goes silent for long stretches and you can't tell whether it's stuck.

Discouraging tools. "Only use tools when strictly necessary" was meant to save tokens. Sonnet 5.5 takes it literally and answers from memory when it should have searched your codebase.

Stale facts. "Tests live in spec/" stays in CLAUDE.md long after the team moved them to test/. This one isn't about the model at all, but it fails the same way: the agent trusts the file and goes looking in the wrong place.

None of these break loudly. The agent still works, just a bit worse, and it's easy to blame the new model instead of your own instructions.

The fix: /claude-api prompt-audit

Claude Code ships with a skill called claude-api, and prompt-audit is one of its subcommands. Open Claude Code at the root of a repository and run:

/claude-api prompt-audit

Here's what it does, in order.

1. Decides scope and target model without asking. The scope is the whole repository unless you name files. The target is the model you name, or else the model running the audit. Both assumptions go at the top of the report, so you can correct them and re-run.

2. Lists everything that reaches the model as text. That means CLAUDE.md and AGENTS.md at every level, rule files, skills, slash commands, subagent definitions and output styles. If the repository also calls the Claude API, it adds system prompts, tool descriptions and the code that builds requests. It deliberately skips settings files and .mcp.json, because those can hold secrets.

3. Checks where each rule came from. It runs git blame on emphatic lines and asks which failure, on which model, the line was added to prevent.

4. Scans for dated patterns in four groups: old prompting habits like the ones above, brittle skill and config files, tool descriptions, and API request settings.

5. Writes a report and a proposed diff. Every finding has a file:line, the quoted text, the pattern it matches, why it's obsolete, a confidence level, and an action. It doesn't change your files unless you explicitly ask it to.

The part I like most is what it refuses to flag. It isn't a "make it shorter" pass. Context only you know (your product, your quality bar, the reason behind a rule) stays. Exact scripts for risky operations like migrations or deploys stay. And if your files are clean, it says so and proposes nothing.

If you want a narrower scope or a specific model, just say it after the skill name, for example /claude-api audit .claude/skills against Opus 5.5.

A real before and after

Here's a real example. This is the root CLAUDE.md of a React and TypeScript front end my team works on every day. Before we ran /claude-api prompt-audit on it, it was 274 lines. After we took the audit's diff, it's 44.

Most of what went away falls into three buckets.

Things the model already does. The old file had a workflow section that started like this:

- Write well documented code
- Typecheck after making a series of code changes
- Check if the project builds after changes
- Proper state management with useState hooks
- Responsive design implemented throughout

None of these tell a current model anything it wouldn't do anyway. Worse, the typecheck and build lines were vaguer copies of an exact command list further down the same file. Two versions of one rule means the model has to guess which one you meant.

Tutorials for libraries the model already knows. About 90 lines taught react-i18next, with code samples for translations, plurals and number formatting. Another 90 documented how to use our analytics hook. The new file replaces the whole i18n tutorial with the two rules that are actually specific to this project:

- Always use translation keys via useTranslation('namespace') — never hardcode user-facing text
- After adding translations, run npm run i18n:validate

The analytics section is gone completely. If a task touches tracking, the agent can read the hook itself.

An index of other instruction files. The old file spent 23 lines listing every folder-level CLAUDE.md and what it covered. Claude Code already picks up a folder's CLAUDE.md when it works in that folder, so the index was a second copy of something the tool does for you.

The audit's diff wasn't only cuts, though. Several sections of the old file were just pointers like "for mobile viewport guidelines, see src/components/CLAUDE.md." The new file turns those into one-line rules the model can't guess:

- Use dynamic viewport units (h-dvh, min-h-dvh) — never
  h-screen or min-h-screen
- Always use design tokens (ink-*, surface-*, brand-*,status-*) — never arbitrary hex/rgba values

Those still say "never", and that's fine. Each one names the alternative and encodes a real decision the team made. That's exactly the kind of prohibition the audit is designed to keep.

The file got six times shorter, but shorter wasn't the goal. The goal was that every line left is something the model couldn't have known on its own.

Run it on your skills repo and on your work repos

Start with wherever your team keeps its shared skills or plugin. Drift there multiplies, because every engineer who installs the plugin inherits the same stale instructions.

Then run it in the repositories where you actually ship code. Their CLAUDE.md files rot along with the codebase. The audit checks that every path a file mentions still exists, and that every command it tells the agent to run is still defined in your scripts and manifests. It does that by reading, not by running anything.

It also catches two files that disagree. Say a skill says "use pnpm" and CLAUDE.md says "use npm". The audit uses git history to work out which rule is newer and proposes aligning the older one. If the older rule is a safety rule, it only flags the conflict and leaves the call to you.

If part of your team uses Codex, the audit reads AGENTS.md too. Its model-specific advice is about Claude, but the stale-path and contradiction checks help no matter which agent reads the file.

As for when: every time a new model comes out, or when you change the default model your team uses. Then take the diff one hunk at a time and try the skill on a real task before and after. A removed line is a hypothesis, not a conclusion. If a removal makes things worse, put back a shorter, calmer version of the rule rather than the original.

Treat a model release like a dependency upgrade

Skills are code. They have a dependency on the model, and that dependency gets upgraded without a lockfile or a changelog entry in your repo.

So treat a new model like a major version bump of a library you rely on. Read what changed, run /claude-api prompt-audit, and review the diff like you'd review any other pull request. That's a lot cheaper than spending a month quietly blaming the new model for your old instructions.