writing-great-skills

name	writing-great-skills
description	Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.
disable-model-invocation	true
metadata	{"version":"2026-07-09"}

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 — the single source of truth for every definition. This file is the decision spine only; when a term needs its full meaning, read it there.

Invocation

Default to user-invoked (disable-model-invocation: true) — zero context load. Pay for model-invocation only when the agent must reach the skill on its own, or another skill must reach it. When user-invoked skills multiply past what you can remember, cure the piled-up cognitive load with a router skill.

Writing the description

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

• Front-load the skill's leading word — the description is where it does its invocation work.
• One trigger per branch. Synonyms renaming a single branch are duplication; collapse them.
• Cut identity that's already in the body.

Information hierarchy

Place each piece of content on the ladder — in-skill step → in-skill reference → disclosed reference behind a context pointer — and make these decisions:

• Every step ends on a completion criterion: checkable, and exhaustive where it matters.
• Disclose by branch: inline what every branch needs; push behind a pointer what only some branches reach. The pointer's wording decides when and how reliably it fires.
• Co-locate: a concept's definition, rules, and caveats under one heading.
• Push too little down and the top bloats; push too much and you hide must-have material. That tension is the whole decision. (This skill is all reference — a flat peer-set is a fine arrangement, not a smell.)

When to split

Granularity spends one of the two loads per cut, so split only when the cut earns it:

• By invocation — when a distinct leading word should trigger the piece on its own, or another skill must reach it.
• By sequence — when visible post-completion steps cause observed premature completion and the criterion can't be sharpened further. Hiding only works across a real context boundary.

Pruning

• Keep each meaning in a single source of truth.
• Check every line for relevance.
• Hunt no-ops sentence by sentence, not just line by line; when a sentence fails the test, delete it whole rather than trimming words. Be aggressive — most prose that fails should go, not be rewritten.

Leading words

Hunt for passages begging to collapse into a single pretrained token:

• "fast, deterministic, low-overhead" → tight (one quality restated across a phase → one word).
• "a loop you believe in" → red (a fuzzy gate → a binary observable state).

You win twice: fewer tokens, and a sharper hook for the agent to hang its thinking on. Assume every skill is carrying restatements that leading words retire — go find them.

Diagnosing a misbehaving skill

Match the symptom to its failure mode — premature completion, duplication, sediment, sprawl, no-op — each defined beside its cure in the glossary.

---

Adapted from mattpocock/skills (MIT).