Writing Great Skills

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. This is the construction-quality SSOT: it scores the SKILL.md itself, not the artifact a skill produces (that is lib/quality-rubric.md). skill-creator --eval binds this file as its criteria; the creator self-checks against it before declaring a new skill done.

Invocation

Two choices, trading different costs:

• Model-invoked keeps a description, so the agent fires it autonomously and other skills can reach it. It pays context load — the description sits in the window every turn. Mechanics: write a model-facing description with rich trigger phrasing.
• User-invoked strips the description from the agent's reach: only the human, by name. Zero context load, but it spends cognitive load — you are the index that must remember it. Mechanics: user-invocable: true; the description becomes a human-facing one-liner.

Pick model-invocation only when the agent must reach the skill on its own, or another skill must. When user-invoked skills multiply past memory, use the pack's DISPATCH.md as the routing table instead of adding another router skill.

Writing the description

A model-invoked description states what the skill is and lists the branches that trigger it. Every word is context load, so prune harder than the body: