How to Fix Claude Skills with New Best Practices

TL;DR

Contents lists at the top of long reference files are essential so Claude can read and use them. Test each skill on every model you plan to use and balance degrees of freedom with the task, using scripts for exact steps when needed. Keep references one level deep and use checklists for complex workflows.

Transcript

So, when Claude opens a long reference file inside one of your skills, it doesn't always read the whole thing. It runs a head {dash} 100 command, which basically reads the first 100 lines only to work out whether the reference file is going to add any information that it actually needs. So, if your important rules sit after line 100, as far as Clau... Read More

Key Insights

• Contents lists at the top of reference files ensure Claude can access the relevant information, enhancing reliability.
• Degrees of freedom determine how much flexibility Claude has; high for broad goals, low for exact commands, and medium for templates with variation.
• Test every skill on all models you intend to deploy, because results can vary by model and require different detail levels.
• Keep the skill body under 500 lines and split content into separate, clearly labeled files to avoid deep nesting and unreadable references.
• Nest references carefully and link directly from the skill document to prevent Claude from skipping details when reading.
• Use scripts for low freedom tasks so Claude executes the exact commands every time without reliance on memory.
• For complex skills, provide a step by step checklist that Claude can copy and tick off as it progresses.
• When a skill covers multiple areas, split references by area to prevent irrelevant files from loading during tasks.

Questions & Answers

Q: How can I make Claude read long reference files reliably?

To ensure Claude reads long reference files reliably, place a contents list at the top of the file and keep the body concise. The contents list acts as an index so Claude can jump to the required sections without scanning the entire document. This practice significantly improves the model’s ability to use relevant information during execution.

Q: Why is testing a Claude skill on every model important?

Testing on every model is important because different models respond differently to the same instructions. By evaluating a skill across multiple models, you can calibrate the level of detail and determine whether to keep, remove, or modify instructions. This approach helps maintain consistent performance regardless of the underlying model.

Q: What does low degrees of freedom look like in a Claude skill?

Low degrees of freedom require exact commands or scripts that must run the same way every time. This minimizes variability and risk of unintended changes, which is critical for tasks where mistakes are costly. The script-based approach ensures predictability across runs and models.

Q: How should references be structured for complex skills?

For complex skills, split references by area and keep nesting shallow. Each area should have its own reference file linked directly from the skill document. This reduces the chance of Claude missing important details and makes it easier to locate the right information during task execution.

Q: What is the role of a checklist in Claude skills?

A checklist provides a clear, repeatable sequence for Claude to follow. By copying and ticking off steps, Claude can track progress and reduce missed steps. This is especially valuable for multi-step or high-stakes tasks where consistency is essential across runs and models.

Q: What should I do when a skill must work with multiple models?

When a skill must work with multiple models, design it to accommodate each model’s needs by testing with all planned models and adjusting the level of detail accordingly. Use model-specific guidance in the YAML front matter to indicate intended models, and tailor instructions to avoid over-prescribing for models that perform better with less guidance.

Q: How should references be linked to avoid the head-100 problem?

To avoid the head-100 problem, link every reference file directly from the skill document (one level deep). Do not rely on chains where one file only points to another. Direct linking ensures Claude can access the target information without missing lower sections during partial reads.

Q: What is the best practice for nesting reference files?

Best practice is to keep the skill body under a reasonable limit and split content into separate files. Then, keep all references directly linked from the skill document, and avoid deep nesting where Claude might only preview top-level content. This structure improves reliability and readability for both humans and the model.

Summary & Key Takeaways

• A practical upgrade guide for Claude skills focuses on making reference files readable by including a contents list at the top and avoiding hidden content deeper than one level. It also recommends testing skills across multiple models to account for differences and using modular structures to improve reliability. Finally, it highlights checklists for complex tasks to ensure consistency.

• The video emphasizes that skills should adapt to model differences, with a mix of high, medium, and low degrees of freedom depending on the task, and that scripts are preferred for exact, repeatable steps to reduce variation.

• The speaker provides a blueprint for organizing skill files, including nesting, references, and the early content listing concept, to ensure Claude can access the needed information efficiently and consistently across models.