writing-great-skills

When to Use

Use when this workflow matches the user request: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.

_Source: mattpocock/skills (MIT)._A skill exists to wrangle determinism out of a stochastic system. Predictability — the agent taking the same _process_ every run, not producing the same output — is the root virtue; every lever below serves it.

Bold terms are defined in [GLOSSARY.md](GLOSSARY.md); look them up there for the full meaning.

Invocation

Two choices, trading different costs:

• A model-invoked skill keeps a description, so the agent can fire it autonomously _and_ other skills can reach it (you can still type its name too). It contributes to context load — the description sits in the window every turn. Mechanics: omit disable-model-invocation, and write a model-facing description with rich trigger phrasing ("Use when the user wants…, mentions…").
• A user-invoked skill strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Zero context load, but it spends cognitive load: _you_ are the index that must remember it exists. Mechanics: set disable-model-invocation: true; the description becomes human-facing — a one-line summary, trigger lists stripped.

Pick mo