When Your Skills Are Too Well-Written for Claude 5.5

When Claude's Opus 5.5 shipped, Anthropic's updated Skills guide flagged a specific risk: Skills written for earlier models may degrade in output quality on the new model. The degradation does not raise an error flag, just output that is a little off, a little over-explained, occasionally too rigid where the model now handles nuance without help. If you have a Skill producing output that looks right on first read and wrong on second, there is a reasonable chance the Skill itself is the source of the problem, not the model and not the task.

The Anthropic documentation is plain about the organizing constraint, and it threads through everything that follows: the context window is a shared resource, and performance degrades as it fills. Every practice in the updated Skills guide is a response to that constraint. The question is how to write Skills that spend their tokens doing work the model cannot do without them, and trust the model with everything else.

The Failure You Are Probably Misreading

When a Skill starts producing plausible-but-wrong output, the obvious diagnosis is that the instructions are not specific enough. The reflex is to add more. In the Claude 5.5 era, that reflex is often exactly wrong.

The updated Anthropic guide on Skill authoring is direct on this point: Skill content competes for space with system prompts, conversation history, and every other Skill's metadata. A Skill written to be thorough is a Skill spending tokens explaining things Claude 5.5 already knows, which means it is also a Skill crowding out the context that actually matters: your firm-specific prices, your internal exception rules, the business logic that lives nowhere except inside your own Skill file.

The failure mode is over-specified Skills written to an older model that required more scaffolding, now running on a model that finds the scaffolding in the way rather than helpful. There are three specific causes worth tracing before you start rewriting anything.

Cause One: The Skill Was Written for a Different Model

Anthropic's updated guide recommends testing existing Skills against the specific model tier that will actually run them. This is not a soft suggestion. A Skill written for an earlier model tier may have been built with more scaffolding than Claude 5.5 requires, because that scaffolding genuinely helped at the time. Claude 5.5 arrives at the same conclusions faster and with less prompting, so those scaffolding sections now cost tokens without contributing anything.

The practical consequence is that Skills written for older models can degrade output quality on Claude 5.5, because the model is trying to reconcile extensive instructions with its own better judgment, and the reconciliation sometimes goes sideways. The guide's position is precise: strip explanations of things Claude already knows, and keep only firm-specific data like prices, terms, and internal rules.

Before you audit anything else about a Skill, ask whether it was written for an earlier model tier than the one now running it and whether it has been retested since then on that current model. If the answer is yes and no, that retest is the first thing to schedule.

Cause Two: Instruction Rigidity Mismatched to Task Consequence

The updated guide defines three degrees of freedom for Skill instructions, and matching the right degree to the right task is probably the most consequential authoring decision you will make.

The principle is consequence. When a task is reversible and judgment-dependent, high freedom produces better results. When a task is irreversible, has regulatory implications, or requires exact compliance with an internal policy, low freedom is not optional.

The mismatch that surfaces most often in practice is high-consequence tasks written with medium-freedom instructions, because medium feels thorough without feeling restrictive. An invoice approval workflow described in prose with "should" and "recommend" language is technically a medium-freedom Skill, and that is a problem if the actual policy is that no invoice above a certain threshold leaves without a second signature. The Skill feels like it covers the rule. In practice, it leaves room for Claude to reason around it.

Cause Three: File Structure That Buries the Critical Content

The updated guide recommends a progressive disclosure structure: only the Skill's name and description load at startup, while the main Skill file and any sub-files load on demand when the Skill becomes relevant. This is a sound architecture for keeping startup context lean, but it introduces a depth problem that is easy to miss.

Claude 5.5 may read only the first 100 lines of a file nested more than one level deep from the main Skill file. If your critical constraints, your escalation rules, your non-negotiable exception handling sit in a third-level file because the structure seemed organized and logical when you built it, Claude may not be reading them. The output will look like the Skill is working. The constraints will be missing.

The guide's own recommendation is one level deep from the main Skill file. Sub-files that reference further sub-files are structurally risky regardless of how well-labeled they are. If you have a Skill with nested references, the question to ask about anything load-bearing is whether it sits within one level of the main file and whether the main file carries a table-of-contents header that makes the sub-file structure visible at the top rather than discoverable only by navigation.

What the Updated Guide Adds Beyond the Fixes

Once the three failure causes are addressed, there are a few authoring practices in the updated guide worth building into new Skills from the start rather than retrofitting later.

Hooks for non-negotiable rules. The updated guide recommends encoding rules that must never be broken as hooks rather than prose instructions. A hook is code that fires at a defined moment in the workflow regardless of what the Skill's prose says, which means Claude cannot reason around it or interpret it charitably. If the rule is "no invoice over $10,000 without explicit sign-off," a prose instruction that says the same thing is a statement Claude will apply carefully most of the time. A hook that enforces the same rule is a gate. These are different things, and for genuinely non-negotiable constraints, only one of them is actually non-negotiable.

Description writing as a discovery mechanism. When Claude is selecting from a large library of Skills, the description is the selection signal. The updated guide is specific: descriptions must state both what the Skill does and when to use it. A description that only covers function will be outcompeted by a Skill whose description also covers trigger conditions, because the model is matching a situation to a Skill, not just a topic. At 100 or more Skills, a description that omits the "when" is a Skill that will be passed over.

Evaluation before documentation. The guide recommends building evaluations before writing extensive documentation for a new Skill. The instinct runs the other direction: write thorough instructions, then test to confirm they work. The problem with that sequence is that you are testing against your own mental model of the task rather than against the actual gap the Skill needs to fill. Using one Claude instance to author the Skill and a separate instance to test it against real tasks surfaces that gap before you have invested heavily in instructions that address the wrong problem.

What to Do on Monday

Pull the Skills your team uses most often and check each one against the model tier currently running it. If any were written without a subsequent retest on Claude 5.5, schedule that retest before adding or modifying any instructions.

For each Skill in that list, ask three things. First, does every instruction in this file cover something Claude 5.5 cannot reasonably infer on its own, or is some of it scaffolding that an older model tier required and this one does not? Second, does the degree of freedom match the actual consequence of getting this task wrong, with low-freedom instructions on anything irreversible and high-freedom only where judgment genuinely improves the result? Third, is every load-bearing rule within one level of the main Skill file, and does the main file carry a header that shows the structure rather than assuming someone will discover it?

The Anthropic Skills guide is at https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices. The rules have not changed, but the model running them has, and those are different problems with different solutions.