🧭 What changed (and what didn’t)
Videos are circulating about “10 new rules” for skills. After checking Anthropic’s official best practices page and the Claude Code docs, the basic rules have been stable for about a year. What changed were the models: Fable 5, Opus 5.5, and Sonnet 5.5 follow instructions more closely and do more on their own. A skill written for older models still works, but it may carry dead weight.
The warning that prompted this lesson
According to the prompting guide cited by skill-creator-plus, skills written for older models are often too prescriptive for 5.5 models and can make the result worse. We couldn’t find this statement in the official documentation; treat it as a hypothesis to test in your skill, not as an Anthropic rule.
Stable (already covered in the course)
- ›SKILL.md under 500 lines
- ›Progressive disclosure in three levels
- ›Description as a trigger: what it does and when to use it
What this lesson adds
- ›Degrees of freedom by step
- ›Character limits and the 5,000-token cutoff
- ›Hooks in the skill, no reasoning requests, checklist with fallback
🎚️ Degrees of freedom: high, medium, low
The official docs say to adjust how specifically you define each step based on how fragile it is. Anthropic's analogy: on a narrow bridge with cliffs on both sides, use exact guardrails; in an open field, give a direction and trust the person. For each step, ask: "what if the agent does this step differently?"
High
Plain-text instruction. Several approaches work, and context decides.
E.g., code review, brainstorm.
Medium
Model or script with parameters. There’s a preferred default, and some variation is acceptable.
E.g., weekly report.
Low
Exact script, with few or no parameters. Errors are costly, or the order can’t change.
E.g., invoice, tax, bank migration.
one skill, three levels:
## 1. Draft the post (high) Write in the brand voice. Context decides the angle. ## 2. Build the summary (medium) Use templates/summary.md. Sections may grow or shrink. ## 3. Publish (low) Run exactly: python scripts/publish.py --verify Do not add flags.
💡 Tip
A good skill often combines all three: free-form writing, a model-generated summary, and publishing locked behind a command. Lock everything down and the skill becomes rigid; leave everything open and risky steps are left to chance.
✍️ Third-person description with “when to use”
The description is the only part of the skill the agent sees before choosing it, among possibly more than a hundred. It goes into the system prompt, which is why the docs ask you to third person (“Creates invoices…,” not “I create…” or “You can…”). Format: one sentence about what the skill does, then “Use when…” with the situations and words people actually type. Only include what the model doesn't know: don't explain what an invoice is.
✗ Doesn’t trigger well
- ✗"I help with invoices." (first person, no “when” clause)
- ✗"You can use it for documents." (vague)
- ✗Primary trigger at the end of a long text
✓ Triggers
- ✓"Creates invoices from the time-tracking spreadsheet and sends billing reminders. Use when someone asks for an invoice, billing, or a payment reminder."
- ✓Main use case first
Field maximum description, without XML tags (Anthropic best practices).
Claude Code cuts off description + when_to_use totaled at this point in the skills listing. The agent doesn’t read beyond that.
💡 Tip
When the listing exceeds the budget, Claude Code also drops entire descriptions of rarely used skills. Another reason to put the most important trigger in the first sentence.
🪝 Hooks in the skill frontmatter
Text is followed with judgment: it can be skipped and, after compaction, only the beginning of the skill remains. “Never send an invoice over R$ 50 thousand without approval” in all caps is followed almost every time. A hook is always followed. The new part is that the skill itself can declare its hooks in the frontmatter: they record when the skill is called and stay active for the rest of the session.
SKILL.md (Claude Code):
---
name: safe-deploying
description: Deploys the app to staging with a safety check on
each shell command. Use when the user asks to deploy or ship.
disable-model-invocation: true
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/check-command.sh"
---
The skill is called
The frontmatter hooks take effect at this moment.
The event happens
Before each Bash command, Claude Code runs the script, whether or not the agent follows the skill.
Until the end of the session
The hook remains registered. Use once: true in the hook that should run only the first time it succeeds.
💡 Tip
Keep judgment in the text; make hard rules hooks. Hooks are Claude Code only: on claude.ai, keep the rule in text and near the top.
🗜️ Compaction: only the first 5,000 tokens remain
When the conversation is compacted, Claude Code reattaches only the first 5,000 tokens for each skill in use. An important rule at the end of a long SKILL.md simply disappears in a long session. That’s why the file’s order should reflect importance.
✗ Order that loses the rule
- ✗Project history and general context at the top
- ✗"Important rules" as the last section
✓ Order that preserves the rule
- ✓Rules that must not fail, right at the beginning
- ✓Permanent instructions (“check the output after each change”), not one-off steps
- ✓Details in references/, linked directly from SKILL.md
🚫 Don’t ask for reasoning in the response
Instructions like “write your reasoning step by step” or “transcribe what you thought” may be refused by 5.5 models (the refusal reasoning_extraction). The skill stops halfway without doing the work. Ask for the result: the answer, a short explanation of it, or a summary of the actions.
✗ Replace
- ✗"Show all your reasoning before answering."
- ✗"Think step by step and write down every thought."
✓ Because
- ✓"Start with the result and explain in two sentences why it matters."
- ✓"At the end, list the actions you took."
The other adjustments for new models
- ★Cut the scaffolding, but test first: step-by-step explanations of what the model already knows and repeated common sense are candidates for removal. Only a run with and without the line can prove it was dead weight.
- ★Give the reason: "under 1,536 characters, because Claude Code cuts off the listing there" leaves the model to handle the case the rule didn't anticipate.
- ★Be direct in one sentence: uppercase only for hard rules. When everything shouts, nothing stands out.
- ★Explicit verification: say how and when the work is checked; for long-running tasks, a subagent that didn’t do the work checks it against the specification.
☑️ Checklist copied + “return to step X”
For a multi-step task, the docs recommend giving the agent a checklist that it copies into its own response and checks them off. Each step ends with a “done when…” that can be verified, and the list says where to return when a check fails. That way, the agent doesn’t skip steps or declare victory too soon.
in the SKILL.md:
Copy this checklist into your reply and tick each step: - [ ] 1. Load the timesheet done when: every row has hours - [ ] 2. Compute the totals done when: sum matches the sheet - [ ] 3. Render the invoice done when: PDF opens, 1 page - [ ] 4. Validate python scripts/validate.py out.pdf If step 4 fails on the total, go back to step 2.
💡 Tip
The check doesn't have to be code: comparing the draft with the style guide and listing every deviation is also a verification loop. Run it, fix what failed, and repeat until it passes.
🔎 Audit before rewriting
Don’t rewrite skills from memory: measure them. The INEMA project auditar-skills is the mirror of skill-creator-plus ). (RoboNuggets, MIT license), with a guide in Portuguese. The validator is pure Python, requires no installation, and makes no API calls: it checks the mechanical parts of every skill in a folder in about one second.
inside the auditar-skills folder:
python3 ~/.claude/skills/skill-creator-plus/scripts/validate_skill.py --all ~/.claude/skillsskills audited on a real machine (Nei’s)
errors found
skills with no errors
The biggest offenders
- ST5A reference with more than 100 lines and no summary at the top. A partial read doesn’t show everything the file covers.
- ST4Nested reference: a file that can only be reached through another file may only be previewed (the first few lines). Link everything directly from SKILL.md.
- DS3Description without “when to use,” and without the words people type.
Run the validator
A table for each skill listing errors, warnings, and violated rules.
Choose five
The ones with the most errors or the ones you use most. Auditing the entire library isn't worth the cost.
Report before editing
Ask for the report and choose what to apply. ST5 and ST4 are mechanical fixes.
Test with and without
Before deleting a line, run the skill with and without it. A rule that must always apply belongs in a hook.
📋 Checklist of the 10 rules (copy and use)
Before publishing or reviewing an older skill, go through this list. The button copies it as a Markdown checklist, ready to paste into your editor or your request to the agent.
- SKILL.md under 500 lines; every reference file linked directly from SKILL.md (one level deep).
- A reference with more than 100 lines starts with a summary.
- Degrees of freedom based on risk: free-form text where context decides, a model where there’s a pattern, an exact script where errors are costly.
- Tested on every model that will use it (Haiku, Sonnet, Opus/Fable).
- Only what the model doesn’t know; third-person description, with “Use when…” and the words people type.
- Description up to 1,024 characters; description + when_to_use under 1,536; put the primary use case first.
- A long task has a checklist the agent copies into its response, with “done when…” and “if it fails, go back to step X.”
- Verification loop: run, fix what failed, repeat until it passes.
- Critical rules at the top, because after compaction only the first 5,000 tokens of the skill remain; don’t ask it to write out its reasoning.
- A rule that must not be broken becomes a hook in the frontmatter; list packages with the installation command.
💡 Sources
Anthropic’s skills best practices guide (platform.claude.com), Claude Code docs on skills, hooks, and context window, checked on October 6, 2026. The warning about overly prescriptive skills comes from the prompting guide cited by skill-creator-plus. The numbers change: check the official link before citing them.
✅ Module Summary · End of Course
You’ve completed the course! 🎉
Five paths, from an overview of the ecosystem to governance and the 2026 rules. Now it's your turn: run the validator on your skills, fix the five worst ones, write the next one using the checklist, and keep learning on the portal.