iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Probably not—but it depends on how much reference material you moved and how often a skill needs it. Anthropic’s guidance treats SKILL.md as the required entry point and supports linked reference files for supplemental detail. Putting brief, frequently needed material back in the main file can be sensible; folding extensive or specialized material into it gives up some of the separation that progressive disclosure is meant to provide.
What belongs in SKILL.md?
Anthropic requires each skill to have a SKILL.md file containing YAML frontmatter and the skill’s core instructions. It is the entry point, not necessarily the place for every piece of information a skill might use. The Agent Skills overview describes a filesystem structure that can include supporting files such as REFERENCE.md.
![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)
That structure enables progressive disclosure: keep the main instructions focused, and make additional detail available when it is relevant. A reference file can therefore hold useful content without putting all of it in the main skill instructions from the outset.
When is moving reference material back a good choice?
Inlining can improve the skill when the material is short, central to the task, and needed on nearly every use. In that case, placing it where the main procedure can use it directly may make the skill easier to follow.
Keeping material separate is generally a better fit when it is long, specialized, or relevant only to certain tasks. Anthropic’s best-practices guidance recommends keeping SKILL.md under 500 lines, linking reference files directly, and avoiding deeply nested reference chains. That is a design recommendation, not evidence that a particular line count guarantees better results.
Choose based on the content and how the skill is used
| Keep it in SKILL.md | Keep it in a reference file |
|---|---|
| The material is brief, foundational, and useful on nearly every invocation. | The material is extensive, specialized, or needed only for particular tasks. |
| It makes the main procedure clearer without making the file difficult to scan. | It can be linked directly from SKILL.md, with a clear note about when to read it. |
| Tradeoff: the main file grows and mixes core instructions with additional detail. | Tradeoff: users or Claude need to follow the link when that detail is needed. |
Anthropic’s Help Center guidance likewise describes REFERENCE.md as a place for supplemental material and recommends pointing to it from the main skill file so it is clear when to load it. The Claude Code plugin-development guidance also advises avoiding duplicated content between a skill’s main file and its references.
Rank #2
Check the result after reorganizing
- Keep the core task instructions and essential workflow in
SKILL.md. - Move detail that is only occasionally needed to a reference file, and link it directly from the main file.
- Tell the reader or Claude what situation calls for consulting that reference; do not make the link’s purpose implicit.
- Remove duplicated instructions so the main file and reference do not become competing sources of truth.
- Review whether the main file remains easy to scan and within Anthropic’s recommended length guidance.
There is no documented token-saving figure or measured quality comparison that makes one layout universally superior. The practical test is whether the main file stays focused while relevant detail remains easy to find.
Free tools Windows power users keep installed
One-click scans. No signup required.
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.
