references/ or assets/: where a skill's extra files belong
Some files in a skill are for Claude to read; others are for Claude to copy into the user's project. Keeping the two apart makes a skill clearer and cheaper.
Once a skill has more than a SKILL.md, its extra files tend to pile up in one folder. Splitting them by purpose makes the skill easier for Claude to use and for people to maintain.
| Folder | For | Examples |
|---|---|---|
| references/ | Claude to read | Component recipes, rules in depth, API notes |
| assets/ | Claude to use in output | Templates, starter files, fonts, images |
| scripts/ | Claude to run | Validators, generators, preflight checks |
Say what to do with each
SKILL.md should tell Claude which references to read, which assets to copy, and which scripts to run, each at the right step. A file nobody points to is dead weight.
The full layout is in skill folder structure, and running scripts well is in scripts or instructions.
Questions
What is the difference between references and assets in a skill?
References are read by Claude to understand how to do the job. Assets are files used in the output: templates, starter files, images or fonts to copy into the project.
Does Claude read asset files?
Only if a step needs to. They are meant to be used or copied, not studied, so they do not need to be loaded into context to be useful.
Can one file be both?
A token CSS file can be both read and copied. Put it where its main job is, and say in SKILL.md what to do with it.