The references folder: keep a skill small until it needs to be big
SKILL.md is read whenever a skill is active; files in references/ only when needed. How to split a skill that way so most turns cost little context.
Everything in SKILL.md is loaded whenever the skill is in use, and it stays in context while it is. That makes SKILL.md expensive real estate. The references/ folder is where the long material goes, read only when a task needs it.
The split
| SKILL.md | references/ |
|---|---|
| The hard rules, ten or so | Full token file, every value |
| When to open which reference | Component recipes in working code |
| What the look or method is not | Long examples, edge cases, API notes |
Point at references explicitly
A reference Claude does not know about is never opened. Name each one in SKILL.md with the moment it matters:
1. Read references/tokens.css and copy it into the global stylesheet.
2. Read references/components.md for the card, buttons and hero.Our design skills are built this way: a short SKILL.md of rules, and tokens and recipes in references/. The cost argument, with how to measure it, is in what a skill costs you in context, and the whole layout is in skill folder structure.
Questions
What goes in a skill's references folder?
Long material Claude needs only sometimes: full token files, component recipes, API notes, examples. SKILL.md keeps the rules and says when to open each reference.
Will Claude read the reference files automatically?
It reads them when SKILL.md points to them and the task needs them. Name each file in SKILL.md and say when it is relevant, or it may never be opened.
How short should SKILL.md be then?
Short enough to hold the rules and the map of references. The details belong in the references.