Examples, references, templates, and helpers

A skill that grows gets worse, because everything in SKILL.md loads whenever the skill fires. The craft is deciding what earns a place in the main file and what belongs in a supporting one.

One example, chosen carefully. The same rule as prompting: one representative input and output sets the pattern. The risk specific to skills is overfitting — give a single example with a very particular shape and the skill starts treating its incidentals as requirements. Pair the example with a general rule so the two can be told apart, and test with a case that's meaningfully different.

Depth goes in a reference file. The main file stays scannable, and a linked reference loads only when the work needs it. This is the difference between a skill that costs a little context whenever it fires and one that costs a lot every time to be useful occasionally.

A template is a skeleton, not sample content. Put the stable output structure in the skill and say when to copy it. Two outputs should share the structure without sharing the example's details — if the second one mentions the first one's subject matter, the template has example content baked into it.

A helper script is for what shouldn't be improvised. A deterministic transformation — reformatting, validating, extracting — is better done by code that behaves identically every time than by a model re-deriving it. Document its inputs and outputs, and make sure it fails clearly on bad input rather than silently producing something wrong.

Loading your workspace…