There’s a particular dishonesty that creeps into writing about the future. You describe the thing everyone should do, or the way a technology will develop, you make it sound clean and inevitable, and you never have to find out whether it survives contact with a real afternoon. My book has a chapter that tells technical writers to build an AI skills library which is a set of small, saved, repeatable tools that each do one job well. It’s good advice. And it nagged at me that I’d written it without doing it. I’m the worst at doing for myself what I tell others to do.
So I built the library my own book describes. Here’s what it actually looks like, and what I learned from finally rolling up my sleeves and getting it done.
A skill is not exotic
Start here, because the word sounds bigger than the thing. A skill is a saved package, whether a role, an input, a few explicit steps, a defined output, and one guardrail that captures how to do a job so neither you nor the machine has to reinvent it each time. That’s the whole of it. Write down how you’d hand a task to a competent colleague, and you’ve written a skill. Save it once, run it forever, sharpen it as you go. Pick any mundane, manual task that you do every day and ask an AI agent to turn it into a skill. You’ll be surprised at how easy it is!
The thing technical writers always knew about AI that the rest of the world is starting to realize is that it is all words. A well-written skill is basically a great example of solid technical writing fundamentals. Progressive disclosure, concision, clarity of language, precision, etc.
The six I started with
I built the skills that, as a writer, enhance tasks I typically need to do:
- a user simulator that reads a page as a confused first-timer and reports exactly where a real person would get stuck
- a structure advisor that ignores your prose entirely and judges only the order, progressive disclosure, how quickly can someone find the critical information on the page
- a neighborhood explorer that maps a page’s parents, siblings, and children before you touch it, so you don’t rewrite the page that already lives next door
- a style checker that audits a page against style guide rules
- a terminology enforcer that holds the line on your branded terms
- an impact reporter that turns a chunk of doc work into a plain sentence about what it did for users and finds relevant data (if available)
Each skill is powerful, but the real magic happens when you chain them. They become a pipeline: explore, draft, simulate, check, ship. The beauty of it all is that none of them took an afternoon to develop.
The moment it earned its keep
I built the user simulator first, and then pointed it at a page of a book I’m writing about technical writing and AI. I told it to read as a newly hired lone writer trying to follow along and implement some of the things I was describing.
It came back with the thing I’d half-known and never fixed, that I knew I would have to return to at some point but kept putting off. The two most useful parts had no how to so the motivated newcomer would be left trying to imagine how they would do it. It flagged the terms I’d used without grounding them. It named the access to experience and ideas I’d blithely assumed the reader already had.
I couldn’t see any of it, because I already knew how it worked. It seemed obvious to me. The tool didn’t know which is precisely why it could discover my bias. That’s the first honest user, bottled: the objective read the author can never give their own page, available on demand instead of whenever you can talk/bribe a colleague/friend/family member into it.
What I learned building my skills library
A few things only showed up once the ideas had to run.
Skills are grown, not written. My first draft of the user simulator flagged things I didn’t care about and missed things I did. Every miss was a wording fix, a tweak, or revision. After a few rounds I got it to a pretty good state. You don’t author a skill perfectly and ship it; you iterate until you get the quality of outcome you need.
The guardrail is the whole game. The most important line in the user simulator is never fix anything, and never reassure. Delete that, and it turns into a friendly assistant that smooths over the exact friction you built it to find. The constraint isn’t a footnote to the skill. It is the skill. Remember, it is critical that you develop AI immunity! It will enthusiastically lie to you and state incorrect things with confidence. It will sycophantically try to win you over. It’s weird.
A machine-readable style guide changes what consistency even means. Written for a human, your style guide is a document you enforce after the fact, that a new team member reads and quickly forgets, that a dutiful editor periodically dusts off to update lovingly. Written as rules a machine can apply, it’s enforced while the draft is being made, that means your editor/reviewer/mom spends significantly less time redlining style violations and more time with the content itself. “Keep sentences short” is a wish to a human who loves to go on and on without ever realizing it themselves like a certain someone I know (me). To a machine it is an instruction. Consistency stops being something you police and becomes something baked in.
The part you can’t hand over
Lay the whole pipeline out and you notice something. Nearly every node can be a skill: explore, draft, check, simulate, publish. Nearly every one. But not the writer. The writer is the human who decides what’s true, what matters, what to cut, and whether any of it serves the person on the other end. That’s not to say you can’t have a skill to generate drafts, but at the end of the day words, like code, can be destructive. The wrong words about a product, service, company, person can evaporate trust and cost money and reputation. Build the library and you don’t automate yourself out of the job; you automate everything that was never the job, so you can spend all of your judgment on the part that is.
Start with one
You don’t need a platform or permission. Take one task you did this week — the same way you always do it — and write it down: a role, an input, the steps, the output, and the one thing it must never do. Run it on three real pages. Fix the wording where it missed. That’s a skill, and it’s the first brick in a wall that compounds.
The writers who thrive in this shift aren’t the ones who resist the tools, and they aren’t the ones who trust them blindly. They’re the ones who build. So stop reading about a skills library. Go build and have fun!
— adapted from my book-in-progress on technical writing in the age of AI.