writing-great-skills

Front-load the skill's leading word, list one trigger per distinct branch, and cut identity statements already covered in the body. Every word in a model-invoked description adds permanent context load, so prune it harder than the body text.

A model-invoked skill keeps its description so the agent and other skills can fire it autonomously, paying context load every turn. A user-invoked skill sets disable-model-invocation: true, making it reachable only by the human typing its name, with zero context load.

Split by invocation when you have a distinct leading word that should trigger a skill on its own, or split by sequence when visible upcoming steps tempt the agent into premature completion of the current step. Each split spends context load or cognitive load, so it must earn the cut.

This is premature completion, caused by a vague completion criterion combined with visible post-completion steps pulling attention forward. First sharpen the completion criterion to be checkable; only if it stays fuzzy and the rush persists, hide later steps by splitting the sequence.

Progressive disclosure moves reference material out of SKILL.md into linked files reached via context pointers, keeping the top of the skill legible. Inline what every branch needs and disclose what only some branches reach, sharpening pointer wording if it fires unreliably.