writing-great-skills

Front-load the skill's leading word and list one trigger per branch, since every word adds context load. Collapse synonym triggers that rename a single branch, and cut identity statements already covered in the body.

Choose model-invocation only when the agent or another skill must reach it autonomously, since the always-loaded description costs context load. If it only ever fires by hand, set disable-model-invocation: true and pay no context load.

Sharpen the step's completion criterion first so done is clearly checkable, which is cheap and local. Only if the criterion is irreducibly fuzzy and you observe the rush, split the sequence to hide post-completion steps.

Progressive disclosure moves reference material out of SKILL.md into a linked file reached by a context pointer, keeping the top of the file legible. Inline what every branch needs and disclose what only some branches use.

The five failure modes are premature completion, duplication, sediment, sprawl, and no-op instructions. Each has a paired remedy: sharpen criteria, keep a single source of truth, prune stale lines, disclose reference, and delete lines the model already obeys by default.