Anthropic updated its skills best-practice guide, and the new rules largely contradict how people built skills earlier this year. The biggest one: Claude previews long reference files with `head -100`, so anything important below line 100 in a file without a contents list may never be read. The other changes cover matching instruction detail to how fragile a task is, testing skills on every model you'll run them with, keeping references one level deep, adding checklists and self-validation loops, and spelling out dependencies so skills work on someone else's machine.
- Claude often previews a long reference file with `head -100` to decide if it's relevant, so any file over 100 lines needs a contents list at the top or the content below line 100 effectively doesn't exist.
- Anthropic's 'degrees of freedom' idea: high freedom (plain goal-level instructions) for ambiguous tasks like code review or drafting a post, medium freedom (a template with settings) for things like a weekly client report, and low freedom (an exact script, no flags changed) for fragile or consequential steps like database migrations, invoicing or deletions.
- A single skill can mix freedom levels — the writing step of an invoicing skill can be loose while the invoice-creation step is locked to a script; the test is 'what happens if Claude does this differently?'
- Skill output depends on the underlying model, so skills should be tested on Haiku (does it give enough guidance?), Sonnet (is it clear and efficient?) and Opus (does it avoid over-explaining?), and the intended model should be noted in the YAML front matter.
- Older skills written for older models are often too prescriptive for newer reasoning models like Opus 4.5 and can make output worse, so instructions should be cut until performance improves; if Haiku misses a step, make it clearer or turn it into a script, since scripts run identically on every model.
- Keep skill.md under 500 lines and treat it as a contents page; split references by domain (finance, sales, marketing) and link every reference file directly from skill.md — nested references get only partially read because of the head-100 preview.
- For ordered work, give Claude a checklist it copies into its reply and ticks off, including a step that sends it back if verification fails; add a validation loop where Claude checks drafts against a style or brand-voice guide, fixes issues, and re-checks until it passes.
- Build for portability: never assume a library is installed — put an 'install the required package' line next to every script, which Claude skips if the dependency already exists.
Reframes skill writing from 'be as precise as possible' to deliberately choosing how much latitude each step gets.
Anthropic say the detail in the skill should depend on how fragile the task is, and how much it varies. So, they call this setting appropriate degrees of freedom, and there are three different levels to this.
A concrete diagnostic procedure that turns vague 'model differences' into a repeatable test and a specific fix.
If Haiku misses a step, that step either needs to be clearer, or it should be a script... Because a script, remember, runs the same on every single model.
If your important rules sit after line 100, as far as Claude's concerned, they actually don't exist.
Skills developed for older models are often too prescriptive for it, and they can make the output worse.
Most of these fixes weren't about the words inside the skill — the quality of the skill comes from how its files are laid out and what checks they run.