What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Not necessarily. Moving a short, frequently needed reference back into SKILL.md can make a skill easier to use. But if the material is long, specialized, or only relevant to certain tasks, keeping it in a separate file and linking to it from SKILL.md better preserves the progressive-disclosure approach Anthropic recommends.
What belongs in SKILL.md?
SKILL.md is the required main file for a skill. It provides the entry point: its metadata and body tell Claude what the skill is for and give its core instructions. Anthropic’s Agent Skills overview also describes supporting files, including files such as REFERENCE.md, as part of the skill’s filesystem structure. A separate reference file is therefore a supported way to organize supplemental material, not an invalid file type.
![Claude AI for Beginners Bible: [5 in 1] The Ultimate Guide to Automate Your Work, Save Hours Every Week, and Use AI for Real-World Results](https://m.media-amazon.com/images/I/415+fSJacsL._SL160_.jpg)
As an Amazon Associate I earn from qualifying purchases.
Progressive disclosure is the reason to separate material: keep the core instructions in the main file and make additional detail available to be read when relevant. That can keep specialized information from crowding the instructions that matter across the skill’s uses.
When is moving the reference back a good choice?
Inline the material when it is brief, central to nearly every use of the skill, and improves the main procedure without making it difficult to scan. In that situation, requiring the reader or Claude to follow a link for a small, routinely needed detail may add friction without much organizational benefit.
#1 Best Overall
Keep it separate when it is extensive, specialized, or useful only for particular tasks. Link to it directly from SKILL.md and explain when it should be read, so the detail stays discoverable without becoming part of the main instructions by default.
| Organization | Better fit | Tradeoff |
|---|---|---|
Material in SKILL.md |
Short information needed for nearly every use | The main file grows, and specialized detail sits alongside core instructions. |
| Material in a separate reference file | Extensive or task-specific information | Claude or a reader must follow the link when that detail is needed. |
How to judge the change
Anthropic’s best-practices guidance recommends keeping SKILL.md under 500 lines, linking supporting files directly, and avoiding deeply nested reference chains. Treat that line count as guidance for the main file, not as a rule that every reference must be external.
Rank #2
- Check how often it is needed. If most skill uses depend on the information, putting a concise version in the main file may be sensible. If only a subset of tasks needs it, keep the detail separate.
- Check the main file’s length and scanability. If the move makes
SKILL.mdunwieldy or pushes it beyond the recommended length, reconsider the split. - Make separate material easy to find. Add a direct link from
SKILL.mdand state the circumstances in which the reference should be read. - Check for duplication. If the main file and reference repeat the same instructions, decide which one is authoritative and remove the duplicate.
These are practical ways to apply Anthropic’s documented as-needed model; the documentation does not establish a universal frequency threshold for moving content in or out of SKILL.md.
So, was moving the files back the wrong call?
Not on its own. If the files held short guidance needed for nearly every invocation, consolidating it may be the clearer design. If they contained substantial or specialized material, moving everything inline gives up some of the separation progressive disclosure is meant to provide. Anthropic’s plugin-development guidance likewise treats references as a home for detailed material and advises against duplicating it in the main skill file.
Anthropic’s documentation provides qualitative organization guidance, not measured token savings or a performance comparison between the two layouts. Make the choice based on the skill’s actual content and use: keep the entry-point instructions focused, while ensuring any separate reference is clearly linked and read when relevant.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
