AI Guides › Skills & Agents
By Nigel Guy · 2 min read
Most people write a skill description to answer one question: what does this do. That's necessary, but it's the least valuable thing the description does — it's also the part that's easiest to get right by accident, which is exactly why the more important jobs the description is doing tend to get skipped.
The rule: a skill description isn't documentation of what the skill does — it's the thing that decides whether the skill fires correctly, whether anyone else can safely reuse it, and whether you'll trust it six months from now, so write it for those three jobs, not just the first one.
| Job | What it actually needs to do | What happens if it's missing |
|---|---|---|
| Routing | State clearly enough when the skill should and shouldn't fire, including edge cases you've already hit | The skill fires on requests it wasn't built for, or sits unused on ones it was |
| Handoff | Give someone who didn't write it enough context to trust or modify it without asking you | It becomes a black box the moment you're unavailable, and a second copy gets written from scratch instead of reused |
| Memory | Tell future-you, who's forgotten the reasoning, why it works this way and not some other way | You "fix" a deliberate design choice because the reasoning behind it wasn't written down anywhere |
A description that only does the first job — a decent one-line summary of what the skill does — passes a casual read and fails the moment anyone other than its author needs it, or the moment enough time passes that its author has forgotten too.
Skip writing a description that reads well in isolation but says nothing about when not to use the skill — the negative case is often more useful than the positive one, because it's the thing that prevents a misfire six months from now. Skip padding the description with marketing language about how useful the skill is; a description's job is precision, not persuasion, and every word not doing routing, handoff, or memory work is a word making the real job harder to find.