We've been writing skills for centuries. We called them books.

Blog · 5 min read

Ask someone to "write a skill" for their AI agent and you'll watch a strange kind of stage fright set in, as if this were a form of writing nobody has ever done before. It isn't. A recipe is a skill. A field manual is a skill. The laminated safety card behind an airline seat, the incident runbook in the ops binder, the style guide your first editor made you read twice — all of it is the same thing we're now trying to hand an agent: here is how to do the thing, written down so someone else can do it without you in the room.

What's actually new isn't the writing. It's the reader. A cookbook is written for someone flipping through it once, deciding what to make for dinner, maybe skimming the headnote for a good story. An agent doesn't want the story. It wants the oven temperature, the resting time, the "if the dough hasn't doubled, wait twenty more minutes, don't guess." Good instructions have always had that part in them somewhere — we just buried it under everything a human reader also wanted, and an agent needs it dug back out.

The part I kept getting wrong

For a while, "writing a skill" meant something close to translation, and I was bad at it: read a chapter, hold the important bits in my head, retype them into a text box. I'd keep the sentence that sounded authoritative and drop the exact number two paragraphs later, because by then I'd stopped taking notes. What came out the other side was a vibe of the original, not the original — confident-sounding and quietly wrong in a way I wouldn't catch until an agent followed it somewhere I didn't expect.

The alternative I tried next was worse: paste in the whole chapter and hope the agent found the right paragraph under pressure, the way you'd hand someone a forty-page manual and say "it's in there somewhere." Neither of those is really writing a skill. One throws away the source. The other refuses to do the work of turning it into one.

What changed

Skilnu's draft-from-a-document feature does the specific thing I was bad at: it reads the actual document — a PDF, a Word file, a Markdown export — and hands back a draft SKILL.md that keeps the specifics instead of the vibe. Nothing gets published. It's a first pass sitting in the compose form, waiting for me to fix what it got wrong before anyone downstream sees it.

The habit that changed is smaller than it sounds. I stopped asking "how do I explain this to an agent" and started asking "do I already have this written down somewhere." Increasingly, I do: the onboarding doc a former teammate wrote that nobody's opened since, the style guide that used to live as a PDF nobody read past page one, a chapter of a book I keep recommending out loud instead of just handing over. Each of those turned out to be twenty minutes and an edit pass away from something an agent could actually follow — not just something I could badly quote from memory.

None of this makes the drafts free of editing. A model that read your document once still writes like it did: dropping in a summary where you needed a rule, going vague exactly where your source went vague. That part is still on you, same as it's always been on whoever adapts a manual for a new reader. What's gone is the part where you start from a blank page trying to remember what chapter four actually said.

Your shelf is already full of these

The instinct to write a skill from scratch treats every agent instruction as a brand-new kind of document. It isn't. Somewhere on your team's wiki, in a binder in the ops closet, or on an actual bookshelf, most of what you'd want an agent to know is already written down by someone who cared enough to get it right the first time. The job was never writing it. It's finally admitting the manual counts.