Why These Rules Matter Now
The 5.5 generation of Claude models is significantly more capable — and more creative — than its predecessors. That changes the game for skill writing. Skills that worked fine six months ago may now be slowing you down, burning tokens unnecessarily, or producing worse output because they over-constrain a smarter model.
There is a specific behaviour to watch: Claude may only read the first 100 lines of deeply nested files. If your most important guidelines sit below that threshold, the model will never see them. These 10 rules are drawn from the latest official Anthropic guidance, and I have tested each one against real production skills.
If you wrote your skills more than three months ago and have not revisited them, they are almost certainly leaving performance on the table.
<500
Maximum lines for your main skill.md file
100
Lines the model may preview on nested files
10
Rules to audit every skill you rely on
Rule 1 — Progressive Disclosure
Keep your main skill.md under 500 lines. Everything else — pricing tables, client lists, scripts — gets split into its own file and linked from the main document. Claude only loads what it needs, when it needs it.
The main file works like a table of contents. Claude opens linked files only at the step that actually requires them, saving you tokens on every run.
If file A links to file B, and file B links to file C, Claude may only preview the first 100 lines of file C. Keep your references one level deep whenever possible.
Progressive disclosure: the main file links to siblings, and Claude opens only the one it needs at each step.
Rule 2 — Content Lists at the Top
Any file over 100 lines needs a short content list at the very top — a table of contents that tells the agent what is inside before it spends your tokens reading the whole thing. Even when Claude only previews the first 100 lines of a nested file, a content list lets it jump straight to the section it needs.
Without content list
pricing.md — 200 lines
Line 1–50: Standard rates
Line 51–120: Enterprise tiers
Line 121–160: Volume discounts
Line 161–200: Payment terms
Claude previews lines 1–100 and never sees discounts or payment terms.
With content list
pricing.md — same 200 lines
Line 1–6: Contents index
— § Standard rates … line 8
— § Enterprise tiers … line 58
— § Volume discounts … line 128
— § Payment terms … line 168
Claude reads the index in preview, then jumps directly to the section it needs.
I keep the content list under six lines. If you need more than six sections, your file is probably too long — split it further per Rule 1.
Rule 3 — Set the Degrees of Freedom
Not every step in a skill needs the same level of control. Where a task is risky or consequential, you give tight guardrails. Where it is exploratory, you let the model be creative. Anthropic calls this "degrees of freedom," and there are three levels.
| Level | What it means | When to use | Example |
|---|---|---|---|
| High | Plain instructions. Tell it what you need. | Brainstorming, exploration, ideation | "List ways to automate our onboarding" |
| Medium | A template with a few settings. Shape is fixed, detail varies. | Weekly reports, summaries, drafts | Template for a status update, but new info is welcome |
| Low | An exact script. Every field, every value, locked. | Invoices, tax documents, compliance | Invoice must match the job list to the dollar |
One skill can mix all three levels. In my invoicing skill, writing the client email is high freedom, but the line-item calculation is locked to a script. Match the freedom to the risk, not to the skill.
The 5.5 models are notably more creative than their older counterparts. If your entire skill is locked to low freedom, you may be wasting that capability and getting rigid, less useful output.
Rule 4 — Test on Every Model You Ship With
A skill is only as good as the model running it. Skills written for older models are often too prescriptive for the newest ones and can actually make the output worse. Here is the one question to check for each tier.
Haiku
Cheaper but less capable. Ask: does my skill give enough guidance for this model to get it right without guessing?
Sonnet
Good middle tier. Ask: is the skill clear, has sensible guidelines, and is token-efficient?
Opus
Top intelligence. Ask: does the skill avoid over-explaining so the model has creative room?
Fable
Strongest reasoning. Ask: are there steps I can remove that this model can figure out on its own?
Testing every skill on every model gets expensive. Start with the skills you rely on the most and the ones where a mistake is consequential. You may also find that some skills you keep running on Opus would work perfectly well on Haiku if the instructions are already tight enough.
Rule 5 — Stop Explaining What the Model Already Knows
Anthropic calls the context window a "public good." Every token you spend explaining a well-known concept is a token you cannot use for your actual task. The fix is simple: keep only what Claude cannot work out on its own — your prices, your terms, your internal rules.
Wastes tokens
"An invoice is a commercial document issued by a seller to a buyer, relating to a sale transaction and indicating the products, quantities, and agreed prices…"
Claude already knows what an invoice is. This paragraph burns context for no gain.
Saves tokens
"Standard hourly rate: $220. Net-30 terms. Tax ID: AU-38291045. Discount threshold: 10% above $5,000. Payment link: stripe.com/inv/acme"
Only company-specific information the model could never guess.
Write the skill description in third person: "This skill creates client invoices and sends payment reminders." First person ("I can help you with invoices") confuses the model when it is deciding which skill to load — especially on lighter models.
Rule 6 — Lay Out Workflows and Checklists
For jobs with many steps, give Claude a clear sequence and an actual checklist it copies into its reply and ticks off as it goes. This stops the model from skipping something critical — a behaviour observed especially with the 5.5 models when steps are implicit.
Define the steps
Write each action as a numbered item. One verb per step.
Add the checklist
Claude copies the list into its reply and marks each item done.
Insert "go back" lines
"If any total does not match the job list, go back to step 2." This catches errors before they ship.
Verify and finish
Claude only marks the task complete when every checkbox passes.
The "go back" line is the most underused pattern I see. One line of instruction can stop a wrong invoice from going out just because a box got ticked too early.
Rule 7 — Build Feedback Loops
A feedback loop is your skill checking its own work. The pattern: run the skill, evaluate the output against a checklist, fix whatever fails, and repeat until everything passes. This is not limited to code — I use it for content, style guides, and structured documents.
For a style guide, the loop checks: is the terminology consistent? Do the examples follow the standard format? Are all required sections present? If anything fails, Claude notes the issue, revises, and checks again.
Self-checking is the single biggest quality lever. The cost of a second pass is nothing compared to shipping work that needs manual correction.
The feedback loop: run → check → fix → repeat until every item passes.
Rule 8 — Use the Three Common Patterns
When your skill needs a more defined output, Anthropic recommends three patterns. Pick the one that best fits the job — or combine them.
Template
A fixed structure with slots. You choose how strict: "always use this exact layout" or "use this as a sensible default and apply your judgment." Best for reports, documents, and structured outputs.
Examples
Pairs of input and expected output. Show the model a prompt you would send and the result you want back. Examples communicate style and level of detail more clearly than any description.
Conditional Workflow
A fork in the road. Claude follows a different set of steps depending on the conditions of the task. For example: "If the client is enterprise, use the long proposal template. If SMB, use the one-pager." This keeps one skill flexible across multiple scenarios without separate skill files.
I use templates for anything financial, examples for tone-sensitive writing, and conditional workflows when one skill serves two audiences. Mixing patterns inside a single skill is fine — do it.
Rule 9 — Build for Shareability
You probably start building skills for your own workspace, but eventually you will need to hand one to a teammate. The principle: never assume that the tools and plugins your skill needs are already installed on someone else's machine.
List every dependency explicitly
Do not write "use the PDF library." Name the exact package and version you tested with.
Include installation instructions
Add a setup section in the skill itself: what to install, which command to run, where to put config files.
Add a "not set up" fallback
Include a note like: "If wkhtmltopdf is not installed, run brew install wkhtmltopdf first." This way the skill tells Claude what to do instead of just failing.
Test on a clean machine
Before sharing, run the skill on a fresh environment where none of your local tools exist. If it breaks, you missed a dependency.
I have shipped skills that worked perfectly on my machine and broke the first time a colleague ran them — every single time it was a missing dependency I forgot to document.
Rule 10 — Use Hooks for Rules That Must Hold
Some rules can never be broken — like "never send an invoice above $10,000 without a human sign-off." You can write that in capital letters in your skill, and most of the time Claude will follow it. But for something this consequential, "most of the time" is not enough.
That is what hooks are for. A hook is a small piece of code that runs automatically at a set moment — before Claude sends something, before it runs a command — whether or not the model is following the skill at that instant.
Pick the two or three rules where a single mistake would really cost you or your business. Move those out of skill text and into hooks. Everything else can stay as instructions.
A hook intercepts actions automatically, enforcing hard rules even when the model is not actively following the skill.
Quick Audit Checklist
Run through this table for every skill you rely on. If you answer "no" to any row, that is your next fix.
| # | Rule | Audit question |
|---|---|---|
| 1 | Progressive disclosure | Is skill.md under 500 lines with one-level-deep links? |
| 2 | Content lists | Does every file over 100 lines have a table of contents at the top? |
| 3 | Degrees of freedom | Does each step have the right level of control — high, medium, or low? |
| 4 | Test on target models | Have you run this skill on every model you plan to use it with? |
| 5 | Optimise writing | Have you removed explanations of things Claude already knows? |
| 6 | Workflows & checklists | Are multi-step tasks laid out as numbered steps with a "go back" line? |
| 7 | Feedback loops | Does the skill check its own output before finishing? |
| 8 | Common patterns | Are you using templates, examples, or conditional workflows where output needs definition? |
| 9 | Shareability | Can a teammate run this skill on a clean machine without manual fixes? |
| 10 | Hooks | Are hard rules (the ones that must never break) enforced by hooks, not just text? |
I run this audit every time I update a model tier or add a new skill. It takes five minutes and has caught drift every single time.