Writing Great Skills

A skill exists to wrangle determinism out of a stochastic system. Predictability — the agent taking the same process every run — is the root virtue.

Invocation

Two choices:

• A model-invoked skill keeps a description, so the agent can fire it autonomously. It contributes to context load.
• A user-invoked skill strips the description from the agent's reach: only you, typing its name, can invoke it. Zero context load, but spends cognitive load.

Pick model-invocation only when the agent must reach the skill on its own.

Writing the description

A model-invoked description does two jobs — state what the skill is, and list the branches that should trigger it.

• Front-load the skill's leading word
• One trigger per branch. Synonyms that rename a single branch are duplication.
• Cut identity that's already in the body.

Information hierarchy

A skill is built from two content types — steps and reference:

1. In-skill step — an ordered action in SKILL.md, the primary tier.
2. In-skill reference — a definition, rule, or fact in SKILL.md, consulted on demand.
3. External reference — reference pushed out of SKILL.md into a separate file.

When to split

Granularity is how finely you divide skills:

• By invocation — split off a model-invoked skill when you have a distinct leading word.
• By sequence — split a run of steps when the steps still ahead tempt the agent to rush the one in front.

Pruning

Keep each meaning in a single source of truth. Check every line for relevance. Then hunt no-ops sentence by sentence.

Leading words

A leading word is a compact concept already living in the model's pretraining that the agent thinks with while running the skill.

Failure modes

• Premature completion — ending a step before it's genuinely done
• Duplication — the same meaning in more than one place
• Sediment — stale layers that settle because adding feels safe
• Sprawl — a skill simply too long
• No-op — a line the model already obeys by default