How to Build Better Claude Skills for New Models

TL;DR

Keep the main SKILL.md under 500 lines, link supporting files directly, and add a contents list to files longer than 100 lines so Claude can locate critical guidance. Match instruction rigidity to task risk, test important skills on the models that will run them, remove unnecessary explanations, and use checklists, feedback loops, templates, examples, and conditional workflows to improve reliability.

Transcript

Claude's 5.5 models are here and the way we build and use skills apparently need to change with them because Entropic just updated their official comprehensive guide for skills and it seems like a lot of what worked before is now either slowing you down or costing you more. For example, did you know that if you have a long skill file, Claude may on... Read More

Key Insights

• Progressive disclosure is a structure in which the main SKILL.md stays under 500 lines and links directly to supporting files. Claude loads specialized material only when the relevant step requires it, reducing unnecessary context use and keeping the primary instructions easier to navigate.
• Deeply nested references can hide critical guidance because Claude may preview only the first 100 lines of a third-level file. Keeping skill references one level deep makes supporting information more accessible and reduces the chance that essential instructions will be overlooked.
• A contents list is important for any supporting file longer than 100 lines. Placing a short section index at the top helps Claude discover information located farther down and navigate directly to the relevant section even when it initially receives only a preview.
• Degrees of freedom should correspond to task risk and output requirements. Plain instructions suit open-ended brainstorming, adjustable templates suit structured work that permits variation, and exact scripts suit consequential tasks such as preparing invoices or tax documents where strict execution is necessary.
• Model-specific testing is necessary because the same skill can behave differently across Haiku, Sonnet, Opus, and Fable. Cheaper models may require additional guidance, middle-tier models benefit from clear and efficient constraints, and smarter models may perform better when unnecessary prescription is removed.
• Efficient skill writing preserves context for information Claude cannot infer independently. Definitions of familiar concepts waste space, while company prices, payment terms, and internal rules add necessary context. Third-person skill descriptions also make skill selection clearer, especially for less capable models.
• Multi-step workflows are more reliable when Claude copies a checklist into its response and marks each step as it proceeds. A return instruction, such as going back when invoice totals do not match the job list, prevents completion merely because every box was checked.
• Feedback loops improve output by requiring Claude to review, revise, and recheck its work until stated requirements pass. Templates establish structure, input-output examples demonstrate style and detail, and conditional workflows direct Claude toward the appropriate steps for the task's specific circumstances.

Questions & Answers

Q: How should a Claude skill use progressive disclosure?

A Claude skill should keep its main SKILL.md under 500 lines and use it as a concise contents page for the overall workflow. Supporting details should live in directly linked files that Claude opens only when a relevant step needs them. For example, an invoicing skill can separate pricing, client information, and scripts so unrelated material does not consume context during every invoice task.

Q: Why should Claude skill references stay one level deep?

Skill references should stay one level deep because Claude may only preview the first 100 lines of a file reached through multiple nested references. If essential guidance appears later in that third-level file, Claude may not encounter it. Direct links from the main SKILL.md make required resources easier to locate and reduce the chance that important instructions will effectively disappear during execution.

Q: When should a skill file include a contents list?

A skill file should include a short contents list at its top whenever it exceeds 100 lines. The list tells Claude what information the file contains before the model spends context reading everything. It also helps Claude find a section located near the bottom, such as discount rules in a pricing file, even when the model initially previews only the file's opening portion.

Q: How do degrees of freedom improve Claude skills?

Degrees of freedom align the strictness of instructions with the consequences and structure of a task. Open-ended brainstorming can rely on plain instructions, a weekly report can use a template with room for relevant variation, and invoice or tax-document creation can follow an exact script. A single skill can mix these levels, allowing creative email writing while tightly controlling financial calculations and document generation.

Q: How should Claude skills be tested across models?

Skills should be tested on each model that will actually run them, especially when the skill is important or errors have serious consequences. Haiku should be checked for sufficient guidance, Sonnet for clarity and efficiency, and Opus or Fable for unnecessary overexplaining that limits creative performance. Testing can also reveal whether a prescriptive skill works reliably on a cheaper model instead of requiring the smartest option.

Q: What information should be removed from a Claude skill?

A Claude skill should remove explanations of concepts the model already understands, such as a general definition of an invoice. It should retain information Claude cannot infer, including company prices, terms, client-specific details, and internal rules. The description should also use third-person wording, such as saying the skill creates invoices and sends reminders, because first-person phrasing can confuse skill selection, particularly on lower models.

Q: How can checklists prevent skipped steps in Claude workflows?

For a multi-step job, the skill should present a clear sequence and instruct Claude to copy a checklist into its response, marking items as work progresses. The workflow should also include return conditions. For example, if an invoice total does not match the job list, Claude should return to the calculation step. This prevents an incorrect result from proceeding simply because the checklist appears complete.

Q: How do feedback loops improve Claude skill outputs?

A feedback loop requires Claude to perform the task, check the result against explicit criteria, fix every failure, and repeat the review until all checks pass. For content governed by a style guide, Claude can verify terminology, example formatting, and required sections. When an issue appears, it should identify the violated guideline, revise the affected material, and complete the task only after the repeated check succeeds.

Summary & Key Takeaways

• Effective Claude skills use progressive disclosure: the main SKILL.md acts as a concise contents page, while directly linked supporting files hold specialized information. Keeping references one level deep reduces the risk that Claude will preview only the first 100 lines of a deeply nested file and miss important instructions.

• Skill instructions should reflect the consequences of each task. Creative work can use plain guidance, structured reports can use adaptable templates, and consequential operations can use exact scripts. Skills should also be tested on their intended models because cheaper models may need more guidance, while smarter models can perform worse when overconstrained.

• Reliable multi-step skills combine explicit workflows with checklists, return paths, and feedback loops. Templates define output structure, examples demonstrate the desired style and detail, and conditional workflows select different steps for different situations. Claude should verify its work, revise detected failures, and repeat the check until all stated requirements pass.