{"slug": "claude-skills-are-outdated-how-to-update-them-to-anthropic-s-new-rules", "title": "Claude Skills Are Outdated: How to Update Them to Anthropic's New Rules", "summary": "Anthropic updated its best practices for building Claude skills, changing guidance on six issues including contents lists for reference files over 100 lines, variable \"degrees of freedom,\" model-specific tuning, file nesting, checklists with self-verification, and dependency handling. The revised guidance warns that Claude often performs a partial read of roughly the first 100 lines of a long reference file, so key instructions placed below that point may never be seen, and it recommends keeping reference files one level deep from skill.md and the skill.md body under roughly 500 lines. Anthropic now advises testing every skill on each model it will run on and adding explicit install steps so skills do not assume a dependency is already installed.", "body_md": "# Claude Skills Are Outdated: How to Update Them to Anthropic's New Rules\n\nAnthropic quietly changed how Claude skills should be built. Here's how to audit existing skills against the new best practices.\n\n## What changed in Anthropic’s Claude skills best practices?\n\nAnthropic updated its guidance on how Claude skills should be structured, and several of the old assumptions no longer hold. The headline problem: when Claude opens a long reference file, it often runs a partial read (roughly the first 100 lines) to decide whether the file is worth loading in full. If your key instructions sit below that point, Claude may never see them. Anthropic’s revised best practices address this and five other issues: contents lists, variable “degrees of freedom,” model-specific tuning, file nesting, checklists with self-verification, and dependency handling.\n\n## TL;DR\n\n- **Reference files over 100 lines** need a contents list (an index of headings) at the top, or Claude may only skim the beginning and miss anything further down.\n- **Degrees of freedom** should vary by task: high freedom for ambiguous judgment calls, medium freedom for templated work, low freedom (often a literal script) for anything fragile or consequential like payments or deletions.\n- **The same skill can perform differently across models** , so Anthropic now recommends testing every skill on each model you plan to run it with and trimming instructions for newer reasoning models that get worse when over-prescribed.\n- **Reference files should stay one level deep** from skill.md. Nesting a file inside another file inside another file makes it likely Claude only partially reads whatever sits at the end of that chain.\n- **Checklists help with multi-step, order-dependent work** , especially when paired with a verification step that sends Claude back to an earlier step if something fails (like confirming citations before finalizing a report).\n- **Skills should never assume a dependency is already installed.** Adding an explicit install step keeps a skill working for teammates or on a fresh machine, not just on the computer where it was built.\n\n## Remy doesn't write the code. It manages the agents who do.\n\nRemy runs the project. The specialists do the work. You work with the PM, not the implementers.\n\n## How do you audit an existing skill against these rules?\n\nStart in Claude Code or Claude Chat (the two surfaces have effectively merged) and go through every skill folder you have. For each one, check:\n\n1. Does any reference file exceed 100 lines without a contents list at the top? If so, add one that mirrors the file’s actual headings.\n2. Is every reference file linked directly from skill.md, or does Claude have to follow a chain (skill.md to file A to file B) to reach it? Flatten anything nested more than one level.\n3. Does the skill.md body stay under roughly 500 lines? If it’s creeping past that, split sections into their own reference files and link them from skill.md, treating skill.md like a table of contents for the whole skill.\n4. Are degrees of freedom applied per step, not uniformly across the whole skill? A single invoicing skill might need loose instructions for drafting a note to a client and a locked-down script for actually generating the invoice.\n5. Has the skill been tested on every model it’s meant to run on, with the results documented?\n6. Does every script-based step include its own install or setup instructions, rather than assuming the environment is already configured?\n\nThis is mechanical work, but it’s also something Claude itself can help with. You can ask it to scan a skill.md and its linked files, flag anything nested more than one level deep, or list every reference file over 100 lines that’s missing a contents section.\n\n## What are “degrees of freedom” and why do they matter?\n\nAnthropic’s update frames skill design around how much latitude Claude should have on a given task, split into three tiers.\n\nHigh freedom means plain instructions with no fixed procedure, used when there are many valid ways to do something and the outcome isn’t fragile. A code review is the example Anthropic uses: check structure, look for bugs, suggest readability improvements, follow project conventions. The right approach depends on the actual code, so Claude is trusted to work out the specifics. For non-technical users, reviewing a sales call transcript or drafting a LinkedIn post falls into this same category.\n\nMedium freedom means a preferred shape with some variation allowed, typically a template with configurable settings (include charts: true/false, output format: markdown or HTML). A recurring weekly client report is a good fit here.\n\nLow freedom means a specific, repeatable sequence with no real variation, used when mistakes are costly or hard to reverse. Anthropic’s example is a database migration: run exactly this script, don’t add flags, don’t change the command. Anything involving money or deletion (raising invoices, removing user accounts) belongs here.\n\nThe practical takeaway: a single skill can mix all three levels across its steps. The test for each step is simple. If Claude doing it slightly differently wouldn’t matter, give it more freedom. If a different approach could cause real damage, lock it down, usually by turning that step into an actual script rather than more detailed prose. Scripts also get executed rather than read into context, so they don’t consume any of Claude’s token budget.\n\n## Why does the same skill behave differently across models?\n\nBecause skills are prompts, and different models respond to the same prompt differently. Anthropic’s guidance now asks builders to test each skill against every model it’s expected to run on, since the right amount of detail has shifted over time.\n\nOlder or smaller models sometimes needed heavy-handed formatting, numbered steps, and emphasis like capitalized “IMPORTANT” flags to avoid skipping steps. Newer, higher-end reasoning models can behave the opposite way: being too prescriptive can actively hurt output quality, because the model second-guesses or over-follows instructions that don’t fit the situation. Anthropic’s guidance for its newer models is to strip out older, overly directive instructions if the model performs better without them.\n\nAnthropic frames this as one evaluation question per model tier: for a smaller model, does the skill give it enough guidance? For a mid-tier model, is the skill clear and efficient? For a top-tier model, does the skill avoid over-explaining? A practical way to apply this is to run your most-used skill on the same task across each model you support. If a smaller model misses a step, either clarify that step or convert it into a low-freedom script, since scripts execute identically regardless of which model is running them. If a higher-end model performs worse with the skill than without it, start cutting instructions until performance improves. If you share or distribute skills, Anthropic recommends documenting the intended model in the skill’s YAML front matter.\n\n## Why do checklists and self-verification improve skill output?\n\nFor multi-step workflows where order matters, such as checking data before building a report from it, Anthropic recommends giving Claude an explicit checklist that it copies into its response and ticks off as it completes each step. The steps don’t need to be rigid or code-like. Anthropic’s research-synthesis example uses five loosely defined steps: read all source documents, identify key themes, and so on, each left intentionally ambiguous in how it gets done.\n\nThe more important addition is a verification step at the end: check every claim against its source, and if citations are incomplete, return to an earlier step rather than marking the checklist complete. This prevents Claude from ticking off a step it technically attempted but didn’t actually pass.\n\nThis pattern generalizes beyond citations. Anthropic describes a loop of draft, check against a standard (a style guide, a brand voice document, a set of requirements), fix what fails, and repeat until everything passes. Over time this loop can improve the skill itself: when a draft fails for a reason not yet covered by the style guide, Claude can propose a new rule, a person approves it, and future runs get checked against the expanded document.\n\n## Is it worth rebuilding skills for portability?\n\n## Other agents ship a demo. Remy ships an app.\n\nReal backend. Real database. Real auth. Real plumbing. Remy has it all.\n\nYes, especially if more than one person or machine will ever run them. A common failure mode is a skill that works perfectly on the builder’s own laptop because required libraries or tools were installed months ago and forgotten, then breaks immediately for a teammate or in a fresh session where those dependencies don’t exist.\n\nAnthropic’s fix is straightforward: never assume a tool is already installed. Instead of an instruction like “use the PDF library to process the file,” the skill should explicitly say to install the required package by name before using it. If the package is already present, Claude recognizes that and skips the step with no cost. If it’s missing, the skill still works. Anthropic recommends putting the install line directly next to any script in the skill, which is a small addition that determines whether a shared skill works immediately or requires ongoing manual setup.\n\n## Frequently Asked Questions\n\n### What is a Claude skill?\n\nA Claude skill is a packaged set of instructions, typically a skill.md file plus optional reference files and scripts, that teaches Claude how to perform a specific recurring task consistently, such as filling out PDF forms or generating client reports.\n\n### Why does Claude only partially read some reference files?\n\nClaude can run a partial read on long files to quickly judge whether they contain information relevant to the current task, rather than loading the entire file into context every time. If a file lacks a contents list and important details sit past that initial read, Claude may never load them.\n\n### What’s the difference between high, medium, and low degrees of freedom?\n\nHigh freedom gives Claude a goal and lets it determine the method, suited to ambiguous or low-stakes tasks. Medium freedom provides a template with some configurable variation. Low freedom specifies an exact, repeatable procedure, often as a literal script, for tasks where consistency is critical and mistakes are costly.\n\n### Do I need to test my skills on every Claude model?\n\nAnthropic’s current guidance recommends it, since the same instructions can produce different results depending on the model. Smaller models may need more explicit guidance, while larger reasoning models can perform worse if a skill is overly prescriptive.\n\n### How deep can reference files be nested in a skill?\n\nAnthropic recommends keeping all reference files exactly one level deep from skill.md. If skill.md points to a file that in turn points to another file, Claude is more likely to only partially read whatever sits at the end of that chain.", "url": "https://wpnews.pro/news/claude-skills-are-outdated-how-to-update-them-to-anthropic-s-new-rules", "canonical_source": "https://www.mindstudio.ai/blog/claude-skills-best-practices-update/", "published_at": "2026-10-02 00:00:00+00:00", "updated_at": "2026-10-02 10:36:04.614907+00:00", "lang": "en", "topics": ["ai-tools", "ai-products", "large-language-models", "artificial-intelligence"], "entities": ["Anthropic", "Claude", "Claude Skills", "Claude Code", "Claude Chat", "Remy"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/claude-skills-are-outdated-how-to-update-them-to-anthropic-s-new-rules", "markdown": "https://wpnews.pro/news/claude-skills-are-outdated-how-to-update-them-to-anthropic-s-new-rules.md", "text": "https://wpnews.pro/news/claude-skills-are-outdated-how-to-update-them-to-anthropic-s-new-rules.txt", "jsonld": "https://wpnews.pro/news/claude-skills-are-outdated-how-to-update-them-to-anthropic-s-new-rules.jsonld"}}