Bundle Files, Templates, and Scripts with a Skill

SKILL.md is read in full whenever the skill fires. Bundled files are read when the instructions reach for them. That single difference is the whole basis for deciding where something goes, and the pattern built on it has a name worth knowing: progressive disclosure. The skill discloses what a run needs at the point the run needs it, rather than everything up front.

So the instructions should hold what is needed to decide and to sequence, and the files should hold what is needed only at a particular step. A twenty-item checklist consulted at the end does not need to be in front of Claude while it is still working out which case it is looking at.

The practical test: if removing a passage from SKILL.md would change how the work is approached, it belongs there. If it would only change what happens at one step, it belongs in a file.

The name is worth having because it tells you what to optimise for. The goal is not a short SKILL.md as an end in itself; it is a cheap common path with the rare path still available. A skill whose one bundled file is read on every single run has not disclosed anything progressively - it has just been split across two files.

A template is the strongest kind of bundled file, because it makes the output shape unambiguous. Rather than describing a table in prose and hoping, you ship the table with its headings and let it be filled in.

Make the template complete, including the sections that will often be empty. An empty heading is an instruction to consider that dimension, and a template with the awkward sections left out quietly teaches Claude to skip them too.

Put guidance inline as short parentheticals rather than in a separate explanation. A column labelled "reachable how (API, export, manual)" carries its own instruction, and nobody has to hold two documents in mind at once.