Ask a team why one of its AI skills misbehaves and the answer is usually about wording: the instruction was too vague, too long, too insistent. Anthropic's own guide to writing Claude skills, Skill authoring best practices, spends most of its length elsewhere. It is about where a skill's files sit, what the model loads from SKILL.md and when, and which checks the skill runs on its own output. We audited our own 82 skills against that guide's checklist on 1 October 2026. Almost everything that needed fixing was layout, and the one fix worth automating is now a hook.
A skill (Anthropic's product name is Agent Skills) is a folder the model loads for a particular job: a SKILL.md file with a name, a description and instructions, plus whatever reference files and scripts the job needs. Claude skills run in Claude Code, on claude.ai and through the API, with different limits on each.[1] If your team keeps saved prompts or custom assistants instead, most of what follows still applies, minus the folder.
Anthropic's skill guide is mostly about layout.
Anthropic's skill authoring page rests on one architecture fact: only each skill's name and description are loaded up front. Claude reads SKILL.md when the skill becomes relevant, opens other files only when it needs them, and runs bundled scripts without reading their source: "Only the script's output consumes tokens."[1] Anthropic calls this progressive disclosure. Nearly every structural rule on the page exists to make that on-demand reading work.
SKILL.md body read when the skill fires · keep it under 500 lines, split before you get there SKILL.md, contents list past 100 lines · scripts are run, not read: only their output costs tokens
Read the figure top to bottom and the budgets explain themselves. The description is the only thing Claude sees before it decides, and it decides among "potentially 100+ available Skills" on that line alone.[1] Once the SKILL.md body loads, every token of it competes with the conversation, so the page asks you to keep it under 500 lines. Everything else waits on disk, "consuming zero context tokens until needed", which only works if Claude can find it from SKILL.md.
The checklist that closes the page makes the same point by its shape. We sorted its 22 items by what each one asks you to change.
SKILL.md under 500 lines details in separate files references one level deep progressive disclosure forward slashes only Six of the 22 items are about the words. The other sixteen are about where files sit, what the scripts do and how the skill gets tested. The sort is ours, and a reader could move an item or two, but no reasonable sort turns the wording into the majority. The video that sent us to the page closes on the same thesis: most of these fixes are about layout and checks, not wording.[5]
What the page says about partial reads.
Anthropic's page makes one narrow, hedged statement about partial reads: when a file is reached through another reference file rather than directly from SKILL.md, Claude may preview it with a command like head -100 instead of reading all of it. The broader version that circulates, in which anything past line 100 goes unread, is not on the page; the video that sent us there opens with it.[5] Here is the page's sentence in full:
head -100 to preview content rather than reading entire files, resulting in incomplete information."[1] Three hedges ("may", "might", "like") and one scope: files reached through another reference file. Nothing in it says content past line 100 is ignored, and nothing says it happens to every file. Two rules come out of it, and both are worth following on the page's own terms.
- Keep references one level deep.
Link every reference file directly from
SKILL.md, so nothing sits at the end of a chain where a partial preview could cut it short. - Give long reference files a contents list.
Any reference file over 100 lines opens with a table of contents. Anthropic's reason: "This ensures Claude can see the full scope of available information even when previewing with partial reads."[1] The 100-line threshold is the page's own number.
The fix is the same whichever account you believe, so the overstatement does little harm in practice. It matters only when someone quotes the claim as Anthropic's, which it is not.
What our SKILL.md audit found.
We ran the checklist against our own toolkit on 1 October 2026: 82 skills, leaving out the platform-synced ones, which we do not maintain. Every finding below is dated. Most are about structure; the last two are about testing.
SKILL.md under 500 lines1 of 82 over: 682 lines, in a skill vendored from an outside projectsplit at its next updateSKILL.md bodies contain Windows pathsleft, by choiceRead the status column before the counts. The finding that looks worst on paper, 35 skills with the wrong kind of path, is one we chose to leave. The one that looks smallest, a single dead link, points at the gap that matters.
The one fix worth automating.
The contents-list rule went in on 1 October 2026, the day of the audit, and it went in as code rather than as a sentence. We backfilled the 18 files, corrected the stale list, and wrote a small script that builds and checks a file's contents list from its headings. A hook runs it after every edit to a skill's reference files and flags a list that is missing or has drifted (it advises; it does not block). Our toolkit health check runs the same script, so it catches edits made outside a session, such as an upstream update to a vendored skill.[3]
We chose a hook over a line in the house style guide because a rule that has to hold on every edit, in every session, belongs in something that runs. That is the lesson of our note on the docs agents actually read: an instruction file is obeyed often, not always, and a check does not forget. The page says the same thing at skill level. Its feedback-loop pattern is "Run validator → fix errors → repeat", and, it says, "This pattern greatly improves output quality."[1]
The dead link is the next candidate. A vendored skill had been trimmed to the files we use, and one of the remaining reference files still pointed at a file the trim removed. Nothing caught it, because nothing checks links inside reference files. One level deep is a rule about structure, and structure is exactly what a script can verify.
What we chose not to fix.
Two findings stayed open on purpose, and each has a reason the page does not cover.
Windows paths. On 1 October 2026, 35 of our 82 SKILL.md bodies contained Windows-style paths. The page's reason for forward slashes is portability: "Windows-style paths cause errors on Unix systems."[1] Our skills run on one Windows workstation, where that error never fires. The rule starts to matter the day a skill is shared, sold to a client or moved to a Linux server, and that is when we will convert it. Rewriting 35 files against a failure that cannot happen here would be churn.
Description length. Here we went the other way and are stricter than the page. Anthropic's limit for the description field is 1,024 characters; our house cap is 400. The platform maximum is a validity limit, not a good length. Every installed skill's name and description are loaded up front, and the page lists "Other Skills' metadata" among the things each skill shares the context window with,[1] so every long description crowds out another skill's. When we measured it on 6 August 2026, our descriptions came to about six times the share of context Claude Code gave the skill listing at the time.[4] A description is an index line. The body can be as long as the job needs.
Lock the steps that touch money.
The page's most useful idea for an operator is not about files at all. It is about how tightly to write each instruction, which Anthropic calls degrees of freedom, and it ties the answer to how fragile the task is.
| Freedom | What the instruction looks like | Anthropic's example | Where it fits in a business |
|---|---|---|---|
| high | prose: a goal and the context | a code review | drafting, research summaries |
| medium | a template, or a script with parameters | a report | a recurring client report |
| low | an exact script: "Do not modify the command or add additional flags."[1] | a database migration | invoicing, deploys, anything that sends or deletes |
The page's analogy is a narrow bridge with cliffs on both sides against an open field. One skill can hold both: the drafting step loose, the step that publishes or invoices locked to an exact command. The video adds a test that makes this usable step by step: what happens if Claude does it differently?[5] If nothing much, loosen the step. If something expensive, lock it, preferably in a script rather than in more prose.
This is also why a bulk rewrite of old skills is the wrong move, even when a model upgrade tempts it. Anthropic's Fable 5 guide does say older skills are "often too prescriptive"; its next sentence is "Review and consider removing older instructions if default performance is better."[2] Removal waits on a comparison. A pass that strips every exact command and every approval step so the skills read more modern removes the guardrails on the narrow bridges. Our note on instruction shelf life covers the wording side of that audit; this note covers the structure. Rewrite one skill at a time, against a before-and-after run.
The rule we mostly skipped.
The checklist's testing block is where our toolkit is weakest. The page is blunt about the order: "Create evaluations BEFORE writing extensive documentation."[1] Find where Claude fails without the skill, build three scenarios that test those gaps, measure Claude's performance without the skill as a baseline, then write the minimum that passes. Few of our skills were built that way.
The page pairs evaluations with a working method that suits a small team. One Claude instance helps you write the skill, a second one uses it on real tasks, and you carry the second one's failures back to the first. It also asks you to test on every model you plan to run, with one question per tier: enough guidance for Haiku, clear and efficient for Sonnet, not over-explained for Opus. And it asks you to watch which files Claude actually opens: "If Claude never accesses a bundled file, it might be unnecessary or poorly signaled in the main instructions."[1] That is a structural check too, and a cheap one. Our six-line eval suite is the same habit, applied to agents.
What this does not prove.
Our audit counts structure, not outcomes. We know which files broke which rules on 1 October 2026. We did not measure whether fixing them made the skills do better work. The page's own method, evaluations against a baseline, is how you would find out, and it is the step we mostly skipped.
The numbers are dated. They describe our toolkit on 1 October 2026. Skills get added and edited every week; re-measure before you quote them.
The page has no revision date. Nothing on it marks a rule as new, so claims that "Anthropic just changed the rules" cannot be checked from the page. Its per-model questions name Haiku, Sonnet and Opus only, which suggests, without proving it, that it was written before the Claude 5 family. Its structural rules do not depend on the model generation, and the Claude 5 prompting guides do not contradict them.
Our toolkit is not yours. 82 skills, one operator, one Windows workstation. A team with five shared skills on mixed machines would rank the forward-slash rule far higher than we do.
SKILL.md under 500 lines, every reference file one link away from it, and a contents list on any reference file over 100 lines. Lock the steps that touch money or cannot be undone. Turn the rules that must hold into a check that runs. And before you rewrite anything, build three test cases and a baseline: it is the only way to know the rewrite helped.
If your team runs AI skills, saved prompts or custom assistants and some of them misbehave, the contact form is the fastest way in. Tell us what you run, and we will send back a written read on where to start, free.