Examples in a skill: fewer, shorter and real
One tight, real example teaches Claude more than five long invented ones. How many examples a skill needs, how long each should be, and where they belong.
Examples are the most persuasive thing in a skill, and the easiest to overdo. Three pages of examples cost context on every turn and mostly repeat each other.
Pick examples that differ
Each example should show something the others do not. For a design skill: one new screen from nothing, one restyle of an existing page, one data-heavy view. Three cases, three different lessons.
Trim to the rule
Cut each example down to the lines that demonstrate the rule. If the point is that numbers use tabular figures, show the number and its style, not the whole page.
Put long ones in references
A one-line example can sit in SKILL.md. Anything longer goes in references/ with a pointer, as in the references folder. The budget reasoning is in what a skill costs you in context.
Questions
How many examples should a skill include?
Two or three that cover genuinely different cases. More examples of the same case add length without adding information.
Should examples go in SKILL.md?
A short one can. Longer examples belong in references/ so they are read when relevant rather than every time the skill is active.
Invented or real examples?
Real, from actual work, trimmed to the part that shows the rule. Invented examples tend to be too clean and teach the wrong edge cases.