Everything You Know About Skills IS OUTDATED

Overview

The video argues that Anthropic’s “skills” best practices have changed, and that older skill authoring patterns can lead to inconsistent or incorrect behavior, especially as Claude models evolve. It provides concrete rules and workflow changes for building more reliable, portable skills.

Key technical concept: the “head -100” reference-file loading problem

When Claude opens a long reference file inside a skill, it may only read the first ~100 lines (via a “head -100” behavior) to decide whether the file will add needed information.

• Implication: If your important rules appear after line 100, Claude may never use them.
• Result: Reference files over 100 lines are less likely to be fully used unless structured correctly.

Updated guide rules / actionable requirements

1) Add a contents list (index) to long reference files (>100 lines)

For any reference file over 100 lines, add a contents list at the top so Claude can:

• read the whole file, or
• jump directly to the relevant section.

Example layout (as described): an API reference with headings such as:

• Authentication and setup
• Core methods
• Advanced features
• Error handling patterns
• Code examples

Suggested workflow: scan your /skills directory (e.g., in Claude Code / Chat) and update reference files accordingly.

2) Use “degrees of freedom” (the right flexibility per task/step)

The video explains guidance that detail level should match task fragility/variance, with three levels:

• High degrees of freedom

  • “Plain instructions”
  • Claude can decide how to accomplish the goal
  • Example: a code review process (check structure, bugs, readability/maintainability, conventions).

• Medium degrees of freedom

  • A template with adjustable settings
  • Examples: charts on/off; output format (Markdown/HTML/etc.)
  • Example: a weekly client report.

• Low degrees of freedom

  • Exact commands / strict sequences
  • Avoid changing flags/parameters
  • Example: database migration, especially for money/deletion workflows—Claude should run a specific script.

Additional analysis from the speaker:

• A single skill can mix these levels across steps (e.g., invoicing skill: high freedom for “writing,” low freedom for “create invoice”).
• Choose low freedom when “doing it differently” has meaningful consequences.
• Low freedom usually means using scripts rather than long plain text instructions.

3) Test skills across every intended Claude model (and adjust instruction detail)

Skill outputs depend on the underlying model that runs them.

The video stresses testing on all models you plan to support (e.g., Haiku, Sonnet, Opus).

Model-specific guidance:

• Older models may need more explicit structuring (e.g., numbered lists, emphasis).
• Newer “reasoning” models can be harmed by overly prescriptive instructions.

Suggested approach:

• Run the most-used skill on the same task with:
  • highly used model(s) first,
  • then Opus,
  • then Sonnet,
  • and adjust as needed.
• If a model misses steps:
  • clarify the step or convert it to a script for consistency.
• If one model performs worse with the skill than without:
  • remove instructions until it improves.

Sharing tip: ensure the skill’s YAML front matter states which model(s) it’s intended for.

4) Organize skill files and references correctly (avoid deep nesting)

• Keep skill.md to ~500 lines (treated like a “table of contents”).
• Split content into separate reference files as you approach the limit.

Scripts behavior: scripts are executed, not read into context—so they don’t consume Claude context like reference files do.

Partition references by domain if a skill covers multiple areas (e.g., finance/sales/product-marketing).

Avoid nested references:

• If skill.md → advance.md → details.md, Claude may only partially open deeper files due to the earlier “head-100”/preview behavior.
• Fix: ensure every reference file is linked directly from skill.md (one level deep).

5) Use proper checklists for longer/complex processes

Anthropic advises breaking complex work into steps plus a checklist that Claude copies and ticks off.

• It’s most appropriate when it prevents order-related mistakes.
• It can also help even if order doesn’t matter, depending on the workflow.

Example workflow: research synthesis with steps such as:

• Read source documents
• Identify key themes
• Verify citations (and if citations fail, go back to an earlier step)

Key feature: self-verification loops using checklist gating (e.g., failed verification stops progression).

6) Add a self-feedback loop (validation → fix → repeat)

Use an iterative loop:

1. Validate
2. Fix errors
3. Re-run until success

Validation doesn’t have to be code—it can be a style guide / brand voice doc.

Example described:

• Draft → review against a guide → revise → review again
• Only finalize when passing.

Bonus learning loop:

• If a failure isn’t covered by current rules, have Claude:
  • propose a new rule,
  • get approval,
  • add it to the doc,
  • and use it in the next run.

The video claims Anthropic’s Fable 5 guide supports that models can update skill guidance based on task learning.

7) Build skills with portability in mind (explicit dependency installation)

Avoid assuming tools/libraries are installed on the user’s machine.

For each script, include an installation line next to it, e.g.:

• “install the required package” and specify the package name
• Claude should skip install if already present

Motivation: ensures the skill works day one for teammates/customers and reduces maintenance burden.

Overall conclusion of the video

The speaker claims these improvements focus less on wording and more on:

• file structure (contents lists, one-level reference links),
• process mechanisms (checklists, validation loops),
• model-aware testing, and
• runtime portability (dependency installation).

Main speakers / sources

• Main speaker: the video narrator (not explicitly identified by name in the provided subtitles).
• Primary source organization: Anthropic (repeatedly referenced via the updated best practices guide and the Fable Five guide).