Source: ai-research/anthropic-skill-authoring-best-practices-2026-10-27.md (primary, fetched 2026-10-27); ai-research/anthropic-skill-authoring-best-practices-evals-2026-07-03.md (earlier snapshot of the same page); ai-research/claude-code-docs-hooks-reference-2026-04-26.md (skill-scoped hooks); raw/Anthropic_Just_Revealed_10_NEW_Rules_for_Claude_Skills.md (secondary relay); raw/Anthropic_Just_Revealed_8_New_Rules_for_Building_Great_Claude_Skills.md (second relay, added 2026-10-28); raw/Everything_You_Know_About_Skills_IS_OUTDATED.md (third relay, Simon Scrapes, added 2026-10-30), checked against ai-research/anthropic-best-practices-claude-code-2026-05-17.md and raw/The-Complete-Guide-to-Building-Skill-for-Claude.pdf
Project: Anthropic platform docs, “Skill authoring best practices” · URL: https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices · Version: page as fetched 2026-10-27
Secondary relay: Robo Nuggets (Jay), “Anthropic Just Revealed 10 NEW Rules for Claude Skills” · URL: https://www.youtube.com/watch?v=VQyYzLJ6xos · Duration: 12:16 · Platform: YouTube · Published: 2026-10-05
Second relay (added 2026-10-28): Ben AI, “Anthropic Just Revealed 8 New Rules for Building Great Claude Skills” · URL: https://www.youtube.com/watch?v=npS5jzOoji8 · Duration: 14:55 · Platform: YouTube · Uploaded: 2026-10-06
Anthropic’s “Skill authoring best practices” page is the canonical guidance on how to write a SKILL.md that Claude finds, reads fully and follows. Jay’s video repackages it as ten rules for the 5.5 models. This article lists those rules, traces each one to the primary text, and records where the video goes beyond the page. The comparison shows that the page did not change in substance between the 2026-07-03 and 2026-10-27 fetches (wording edits only), and that two of the ten rules come from other Anthropic documents.
Key Takeaways
- Keep
SKILL.mdunder 500 lines and link other files one level deep. When a reference file points to another file, Claude may preview the second withhead -100instead of reading it in full. Link every reference straight fromSKILL.md. - Put a table of contents at the top of any reference file over 100 lines, so a partial read still shows what the file contains.
- Match the degree of freedom to the risk. High freedom (plain instructions) where many approaches work; medium (a template or parameterized script) where a preferred pattern exists; low (an exact script, “do not modify the command”) where operations are fragile. One skill can mix all three.
- Test on every model you will run the skill on. Haiku: is there enough guidance? Sonnet: is it clear and efficient? Opus: does it avoid over-explaining?
- Only write what Claude does not already know. “The context window is a public good”; skip explaining what a PDF or an invoice is and spend the tokens on your prices, terms and rules.
- Write the
descriptionin third person (“Processes Excel files and generates reports”, not “I can help you…”). It is injected into the system prompt and drives skill selection among possibly 100+ skills. - Give multi-step jobs a checklist Claude copies into its reply and ticks off, with “go back to step N” lines where a check fails.
- Build feedback loops: run, validate, fix, repeat. The validator can be a style guide plus a checklist, not just a script.
- Use the three output patterns: a template (strict or default), input/output examples, and conditional workflows (“creating new content? follow X; editing? follow Y”).
- Don’t assume packages are installed. Name them and include the install line, or the skill breaks the first time a teammate runs it.
- Move unbreakable rules out of prose into hooks. Skills can declare hooks in frontmatter (for example a
PreToolUsecheck before every Bash call). A hook runs every time; a rule in capital letters is followed most of the time. This rule comes from the hooks reference, not the best-practices page. - Build evaluations first. The page’s process: run Claude without the skill, write three scenarios that test the gaps, measure a baseline, write the minimum instructions that pass. The video does not cover this section.
The ten rules, traced to source
| # | Rule as relayed by Jay | Where it comes from | Fidelity |
|---|---|---|---|
| 1 | Progressive disclosure: SKILL.md under 500 lines, references one level deep, nested files may only get their first 100 lines previewed | Best-practices page: “Keep SKILL.md body under 500 lines”, “Keep references one level deep”, nested references previewed with head -100 | Accurate. The page does not say this is a new-model behavior, as the video implies. |
| 2 | Content lists: a table of contents at the top of files over 100 lines | ”For reference files longer than 100 lines, include a table of contents at the top” | Accurate |
| 3 | Degrees of freedom: high / medium / low, mixable inside one skill | ”Set appropriate degrees of freedom” (narrow-bridge vs open-field analogy) | Accurate. The invoice example is Jay’s. |
| 4 | Test on the models you use: Haiku enough guidance, Sonnet clear, Opus/Fable not over-explained; old skills may be too prescriptive for new models | Page names Haiku, Sonnet and Opus only. The “too prescriptive” point is in Anthropic’s Fable 5 prompting guide ([[prompt-engineering/prompting-claude-fable-5 | Prompting Claude Fable 5]]: “Existing skills may be too prescriptive”) |
| 5 | Concise writing; third-person descriptions | ”Concise is key”, “Default assumption: Claude is already very smart”, “Always write in third person” | Accurate |
| 6 | Workflows and checklists with a “go back” line | ”Use workflows for complex tasks”, “Copy this checklist and track your progress” | Accurate. “Go back line” is Jay’s name for the page’s return-to-step pattern. |
| 7 | Feedback loops: run, fix, repeat; style-guide example | ”Implement feedback loops”, “Example 1: Style guide compliance (for Skills without code)“ | Accurate |
| 8 | Common patterns: template, examples, conditional workflow | ”Template pattern”, “Examples pattern”, “Conditional workflow pattern” | Accurate |
| 9 | Build for shareability: list packages, include install instructions | ”Avoid assuming tools are installed”; “List required packages in your SKILL.md” | Accurate. “Shareability” is Jay’s framing. |
| 10 | Move must-hold rules into hooks; hooks can live inside the skill (secure-operations example) | Hooks reference, § Hooks in skills and agents. Not on the best-practices page. | Accurate source, different document |
“Anthropic just updated the guide.” The video opens with this claim. A line-level comparison of the 2026-07-03 and 2026-10-27 fetches found wording edits only (“Solve, don’t punt” became “Solve, don’t defer”, “multi-step” became “multistep”, link targets updated). No rule was added and the page still names Haiku, Sonnet and Opus with no Opus 5.5 or Fable guidance. Either the video describes an intermediate version not captured here, or it presents the existing page as new.
Hook lifetime differs between sources. Jay says that once a skill with a hook is used, Claude Code keeps the hook running for the rest of the session. The April 2026 hooks reference says skill hooks “are scoped to the component’s lifecycle and only run when that component is active” and are “cleaned up when it finishes.” ^[ambiguous] Test in your own version before relying on either.
Second relay: Ben AI’s eight rules (added 2026-10-28)
Ben’s video, published a day after Jay’s, draws on several Anthropic documents rather than this page alone, and only three of his eight rules overlap with Jay’s ten. Despite the title, none of the eight is new: each traces to a page or guide that predates the video, apart from rule 7, which Ben says is his own. His working method behind the rules is in Ben AI’s Skill-Engineering Framework.
| # | Rule as relayed by Ben | Where it comes from | Fidelity |
|---|---|---|---|
| 1 | Do the task once with Claude, then turn it into a skill (or use Record a skill) | This page, “Develop Skills iteratively with Claude”, step 1: “Complete a task without a Skill … you’ll naturally provide context, explain preferences, and share procedural knowledge” | Accurate. The recording feature is Ben’s addition (Record a Skill). |
| 2 | Focused, task-specific skills; start with the smallest valuable part | Complete Guide PDF: “Pro Tip: Iterate on a single task before expanding”. Ben’s further quote, “multiple focused skills compose better than one large skill”, was not found in the wiki’s copies of Anthropic docs | Partly verified |
| 3 | Treat a skill as a living business process; build in one chat, test in another | Complete Guide PDF: “Skills are living documents”; this page’s Claude A (builds and refines) / Claude B (fresh instance that tests) loop | Accurate. The “best skills began as a few lines” blog quote was not located; it may come from the unread “Lessons from building Claude Code: How we use skills” post. |
| 4 | Add input/output examples | This page: “Examples convey the desired style and level of detail to Claude more clearly than descriptions alone” (Examples pattern) | Accurate. Ben’s “3 to 5, up to 20 for copywriting” is his experience. |
| 5 | Progressive disclosure, with each step naming the reference files to read | This page’s progressive-disclosure section; Ben attributes the “core design principle” and “effectively unbounded” wording to Anthropic’s engineering blog, which the wiki has not captured verbatim | Accurate in substance. Per-step loading is Ben’s refinement; he says the built-in skill-creator often skips it. |
| 6 | Force subagents for research and connector steps | Claude Code best practices: “Claude’s context window fills up fast, and performance degrades as it fills” and “Use subagents for investigation … Subagents run in separate context windows and report back summaries” | Accurate source, different document (not this page) |
| 7 | Give multiple outputs at every human checkpoint | Ben says this is not in the guide but mirrors how Anthropic designs its own skills | Creator practice, no first-party text |
| 8 | Stop unwanted auto-triggering with disable-model-invocation: true | Claude Code best practices: “Use disable-model-invocation: true for workflows with side effects that should be triggered manually” | Field verified. Ben’s extra claim, that the description then stays out of every chat’s context, is not in the wiki’s sources. ^[ambiguous] |
What the two relays agree on: progressive disclosure, examples, and iterative testing appear in both. What only Ben adds: subagent isolation for connector calls (rule 6) and the manual-only trigger (rule 8), both from Claude Code docs, plus the “multiple options” practice. What only Jay adds: degrees of freedom, third-person descriptions, checklists, model-tier testing and hooks.
Third relay: Simon Scrapes’ rules (added 2026-10-30)
Source: raw/Everything_You_Know_About_Skills_IS_OUTDATED.md · Creator: Simon Scrapes · URL: https://www.youtube.com/watch?v=e7TY56-yIvM · Duration: 12:49 · Platform: YouTube · Uploaded: 2026-10-01 (before both relays above)
Simon’s video says Anthropic “updated their best practice guide with six more rules” and lists seven fixes (the closing recap counts nine, including the free audit prompt he offers). Each matches a row in Jay’s table above, so the same fidelity notes apply, including the doubt about an update (see “Anthropic just updated the guide”).
| Simon’s rule | Matches Jay’s row | Notes |
|---|---|---|
Contents list at the top of any reference file over 100 lines, because Claude may preview with head -100 | 1, 2 | He frames the preview as the reason rules after line 100 “don’t exist” for Claude |
| Degrees of freedom: high (plain goal), medium (template with settings), low (exact script); one skill can mix them; ask “what happens if Claude does this step differently?“ | 3 | Low freedom “usually means a script”, and scripts are run, not read into context |
| Test on every model you’ll use and write the intended model in the frontmatter | 4 | The frontmatter note is his suggestion |
SKILL.md under 500 lines; split references by area (finance, sales, product) so unrelated files never load; keep every reference one level deep | 1 | Example: one file per client in a reporting skill |
| Checklists for long processes where order matters, with a “return to step three” line on failure | 6 | He reconciles this with “give the whole job, not steps”: checklists only when order matters |
| Feedback loop: draft, review against a style guide (your voice doc), revise until it passes; have Claude propose a new rule when a draft fails for a reason not yet in the guide | 7 | He relays the Fable 5 guide saying the model is good at updating skills from what it learns |
| Never assume a package is installed; put the install line next to every script | 9 | His reason: skills you share or sell must work on a teammate’s machine on day one |
His conclusion: most fixes concern file layout and checks rather than wording, because newer models write their own instructions from goals. His later October videos add that a skill should hold only the corrections Claude needs after a no-skill run (Advice Reset).
Try It
- Audit your five most-used skills against this checklist: under 500 lines; every reference linked from
SKILL.md; TOC on files over 100 lines; third-person description that says what and when; no paragraphs explaining things Claude knows; packages named with install lines. - Mark each step’s degree of freedom. Lock fragile steps (invoicing, tax, migrations) to an exact script and loosen the creative ones. Skills written for Opus 4.x-era models are the likeliest to be over-specified.
- Pick the one rule in each skill that must never break (for example “never send an invoice above $10,000 without sign-off”) and move it to a
PreToolUsehook in the skill’s frontmatter. - Run each critical skill on the cheapest model you would route it to. If Haiku fails it, add guidance; if Opus output gets worse with the skill loaded, cut instructions.
- Write three evaluation scenarios before editing a skill, and record a no-skill baseline first, per the page’s evaluation-driven process.
Implementation
Tool/Service: Claude Code skills (.claude/skills/<name>/SKILL.md), also Claude.ai and the API.
Setup: None. Anthropic’s built-in skill-creator skill applies most of these rules; Jay distributes his own variant (“skill creator plus”) and an audit prompt through his video description, claiming the built-in one was last updated in March. The wiki’s Building Skills guide records a March 2026 skill-creator overhaul, consistent with that date.
Cost: Testing every skill on every model costs tokens; Jay suggests limiting it to the skills you rely on most and those where a mistake is costly.
Integration notes: A skill-scoped hook, as given in the hooks reference:
---
name: secure-operations
description: Perform operations with security checks
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/security-check.sh"
---Open Questions
- Is there an updated version of the page that the video read? The 2026-10-27 fetch does not contain the 5.5-specific guidance the video attributes to it.
- Hook lifetime after skill use: session-long (video) or component-scoped (April hooks reference)? A current hooks-reference fetch would settle it.
- Does
disable-model-invocation: truedrop the skill’s description from context? Ben says yes (saving tokens in every chat); a fetch of the current Claude Code skills docs would settle it. - Fable and the 5.5 models in the model-testing rule. The page still lists only Haiku, Sonnet and Opus; whether Anthropic intends Fable 5.1 to be tested as “Opus-like” is not stated.
Related
- Agent Skills Overview — how skills load (name and description at startup, body on trigger)
- The Complete Guide to Building Skills — Anthropic’s long-form guide and the evals workflow
- Skill Design Patterns — five patterns at the workflow level
- Four Skill Rules from Anthropic Engineers — an earlier creator relay of Anthropic skill advice
- Hooks — the deterministic layer rule 10 points to
- Prompting Claude Fable 5 — source of the “existing skills may be too prescriptive” guidance
- ARMS Agentic OS — Jay’s skill types, model routing and self-improving skills
- Ben AI’s Skill-Engineering Framework — the second relay’s author, with his prompts for applying each rule