# write-a-skill

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 goal, and every rule below serves it. A skill is loaded by its description and judged by its brevity: the description does the triggering, the body does the teaching.

For the theory behind these rules — the full vocabulary, the information-hierarchy ladder, and the failure-mode diagnostics — load reference.md in this skill folder. The essentials are below; reach for reference.md when a skill is misbehaving or you're deciding how to split one.

House style

• One-word name when possible. Prefer a target argument (/improve ui) or a mode (plan grill/trust) over a family of narrow sibling skills.
• Check the suite first. If an existing skill half-covers the request, extend or combine it instead of adding a sibling.
• Default postures: report first, fix on approval; capture outputs to docs/ (ideas, plans, learn) so sessions compound; end by offering the natural next step (idea → plan, improve → fixes).
• Every skill stands alone. Sibling skills are optional pointers, never requirements — if another skill's rules are genuinely needed, inline the one or two essential lines instead of "follow /x".

Invocation — two kinds, paying two different costs

Every skill spends one of two loads, and the choice of how it's invoked decides which:

• Model-invoked (the default here) keeps a description, so the agent can fire it on its own and other skills can reach it. It costs context load — the description sits in the window every turn. Write a rich, trigger-laden description.
• User-invoked sets disable-model-invocation: true. Only the user, typing its name, can invoke it; the description becomes a human-facing one-liner. Zero context load, but it costs cognitive load — the user is now the index that must remember it exists.