Build skills your team will actually reuse

Anyone can save a note. The hard part, the part that decides whether your brain becomes infrastructure or a graveyard, is writing skills that future agents actually retrieve and apply. This guide is the craft of that: what a reusable skill is made of, what separates the ones that fire from the ones that rot, and how to keep the loop healthy over time.

The four sections, and what each is really for

Every skill has the same four parts. They are not bureaucracy; each one does a specific job, and skipping any of them breaks reuse in a predictable way.

• When to fire: the trigger an agent will recognize later. This is the single most important section, because a skill that never matches its situation is dead weight no matter how good its steps are.
• Steps: the ordered actions, concrete enough to repeat without you in the room. If a step assumes context only you have, it will not transfer.
• Checks: how to know it worked, and the failure modes to watch for. This is what lets the agent verify rather than hope, and catch the case where the steps ran but the outcome is wrong.
• Why it works: the judgment underneath. This is what lets the skill survive small changes instead of shattering the first time a detail shifts.

The trigger is everything

Spend your effort here. A trigger that is too vague ("deployment issues") either never fires or fires on everything, which trains agents to ignore it. A trigger that is too narrow ("the exact stack trace from last Tuesday") never matches again. The target is the recognizable situation: the symptom plus the context that makes it specific, written so an agent who has never seen the problem would still know that now is the moment.

Why it works is what makes it durable

This is the section people skip and the one that determines lifespan. Steps tell an agent what to do; the why tells it what to do when the steps do not quite fit. The world drifts: a flag gets renamed, a path moves, an API changes shape. A skill with only steps breaks at the first drift. A skill that explains why the steps work lets the next agent adapt them. This is also, not coincidentally, the part that decays slowest, because principles outlive their specifics.

Capture the dead ends, too

The most underrated thing you can put in a skill is the alternatives you rejected and why. Without them, the next agent re-walks the dead end you already mapped, which is exactly the rediscovery cost you were trying to eliminate. "We tried X; it fails because Y; do Z instead" is worth more than "do Z," because it inoculates against the wrong turn.

The anti-patterns that kill reuse

• Too generic: advice that applies everywhere helps nowhere specifically. Capture the particular workflow, not the principle.
• No checks: steps without a way to verify them produce confident-but-wrong runs. Always include how to know it worked.
• Buried trigger: if the agent has to read the whole skill to know whether it applies, it will not load it in time.
• Secrets inline: never put keys, tokens, or full transcripts in a skill. Summarize sensitive context; a privacy review redacts PII before saving.

Close the loop, every time

Writing the skill is half of it. The other half is reporting outcomes after it is applied, because that is the signal that decides what surfaces next. Helpful outcomes strengthen a skill through synaptic plasticity and push it up the ranking; stale or wrong ones depress it and eventually retire it. A skill nobody confirms is invisible to the ranking, so even a brilliant one stays buried until the loop closes.

"that skill helped"        →  strengthens, ranks higher
"that was stale, step 2 changed"  →  flags it to refresh

Test before you trust