writing-great-skills

A skill exists to squeeze determinism out of a stochastic system. Predictability — the agent walking the same process every run, not emitting the same output — is the root virtue; every lever below is in service of it.

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

Invocation

Two choices, each with its own cost:

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

Choose model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.

When user-invoked skills pile up past what you can hold in your head, that accumulated cognitive load is cured by a router skill: one user-invoked skill that names the others and when to reach for each.

Writing the description

A model-invoked description does two jobs — state what the skill is, and list the branches that should trigger it. Every word adds context load, so a description earns even harder pruning than the body: