When a SKILL.md crosses a few hundred lines, it has quietly turned into a document. Claude reads the whole body the moment the skill triggers, so every paragraph of API trivia you wrote for one rare branch rides along in context on every invocation. Claude skill references are the fix. You move the detail into separate files inside the skill folder, leave pointers in SKILL.md, and Claude reads those files only when a task needs them.
Anthropic calls this progressive disclosure. The best-practices guide describes three layers: the name and description load at startup, the SKILL.md body loads when the skill triggers, and the Claude skill bundled files load only when Claude follows a reference to them. So a 4,000-line API reference, parked in a referenced file, costs you zero tokens until Claude actually opens it.
Why Claude skill references keep SKILL.md lean
The context window is shared. Your skill competes with the system prompt, the conversation so far, every other skill's metadata, and the user's request. The docs give a hard target here: keep the SKILL.md body under 500 lines, and split content into separate files as you approach that limit.
Take a skill that handles invoices. Ninety percent of runs are "read this PDF, pull the totals." The other ten percent involve filling a form, which needs three pages of field-mapping rules nobody wants loaded the rest of the time. Put the common path in SKILL.md and the form rules in a referenced file, and the cheap case stays cheap.
A lean SKILL.md also keeps the skill honest. It reads like a table of contents: here is what I do, here is where the deep material lives. A bloated one buries the trigger logic under reference dumps, and you stop being able to see at a glance what the thing is for.
How to reference a file from SKILL.md
You link it by relative path, as plain markdown, from inside the SKILL.md body. Nothing more.
## Advanced features
**Form filling**: See [forms.md](forms.md) for the complete guide
**API reference**: See [reference.md](reference.md) for all methods
Claude reads forms.md or reference.md only when the task calls for it. The paths are relative to the skill folder, and you want forward slashes even on Windows, because the runtime treats the folder like a Unix filesystem and backslashes break it. The real pdf skill in Anthropic's repo does exactly this: SKILL.md sits next to forms.md and reference.md, and points at both.
One distinction is worth getting right early, because it changes the token math. Asking Claude to read a file is not the same as asking it to run one. "See reference.md for the field types" means load and read. "Run scripts/fill_form.py" means execute without loading the source into context at all. Say which you mean.
The folders: references, scripts, assets
There is no fixed schema here, and that catches people out. A skill folder is just a directory, and you name the supporting files however reads best. Even so, the docs and the example skills converge on a few conventions worth copying.
Flat reference files live next to SKILL.md, like forms.md and reference.md in the pdf skill. When a skill has several domains of reference material, group them under a reference/ folder instead, which is the SKILL.md references folder pattern most multi-file Claude skills settle on. The mcp-builder skill does this: its reference/ folder holds python_mcp_server.md, node_mcp_server.md, and mcp_best_practices.md. The BigQuery example in the best-practices docs uses the same pattern with reference/finance.md and reference/sales.md, so Claude reading about revenue never touches the sales schema.
Executable code goes in scripts/. Both the pdf and mcp-builder skills ship one, and Claude runs those files rather than reading them, so a 200-line Python utility costs only its output in tokens. If you are writing scripts, the companion piece on Claude skill scripts goes deeper than I will here.
The assets/ convention covers files used in output rather than read for instruction: templates, fonts, the images a skill stitches into a result. The official docs lean harder on scripts/ and reference files than on assets/, so I treat it as a sensible name rather than a mandated one.
Here is a directory tree that pulls it together.
invoice-processing/
├── SKILL.md # lean overview, loads on trigger
├── forms.md # form-filling detail, loaded on demand
├── reference/
│ ├── tax-rules.md # one domain
│ └── currencies.md # another domain
├── scripts/
│ ├── extract.py # executed, not read into context
│ └── validate.py
└── assets/
└── template.xlsx # used in output
Keep references one level deep
This is the rule people miss most often, and ignoring it bites. The best-practices doc says to keep references one level deep: every reference file should link directly from SKILL.md, never from another reference file.
The reason is mechanical. When Claude hits a reference buried inside an already-referenced file, it may only partially read the deeper file, sometimes previewing the first hundred lines with head -100 rather than reading the whole thing. So a chain where SKILL.md points to advanced.md, which points to details.md, which holds the real answer, is one where Claude can stop reading before it ever gets there. Flatten it. If details.md matters, link it straight from SKILL.md.
For any reference file longer than a hundred lines, put a short table of contents at the top. Even when Claude only previews the file, the table of contents tells it what is in there and whether to keep reading.
Can one skill reference another skill?
Carefully, and probably not the way you are hoping. The Agent Skills format describes references as files bundled inside a single skill folder, loaded by relative path. In the current docs there is no "import another skill" directive in SKILL.md, and I am not going to pretend otherwise. What does exist is the metadata layer: every installed skill's name and description sit in the system prompt, so Claude can choose to invoke a second skill on its own. That is coordination through the model rather than a hard link. If you want two skills to work together, write descriptions clear enough that Claude reaches for the second one.
For the wider folder layout beyond references, the Claude skill folder structure guide covers naming and frontmatter.
Splitting a skill well is mostly judgment about what belongs where, and that judgment is what Knack front-loads. You answer a short interview about the workflow you want to capture, and it ships a real Anthropic-format skill folder, SKILL.md plus referenced files already split sensibly, that runs in Claude Code, the Claude apps, Codex, Cursor, and Gemini CLI. If your current SKILL.md is 600 lines and groaning, you already know it. Pull the rare path into a referenced file today.