Technical Writers Should Be the Ones Writing AI Skill Files
If you use AI to write documentation, you’ve probably seen this happen more than once. One prompt gives you a page that follows your style guide perfectly. The next prompt forgets your heading style, renames your product
If you use AI to write documentation, you’ve probably seen this happen more than once. One prompt gives you a page that follows your style guide perfectly. The next prompt forgets your heading style, renames your product, and writes the release notes in a format your team stopped using a year ago, so you end up pasting the same instructions into every conversation and fixing the same mistakes in every draft. For a while I thought this was just the price of working with AI. Then I started writing skill files, and I realised that the fix for this problem looks a lot like the work technical writers already do every day.
What a skill file actually is
A skill file is a set of instructions that teaches an AI tool how to do one specific task the way you want it done. In practice, a skill is a folder containing a SKILL.md file.
It includes a name and a description at minimum, along with instructions that tell the agent how to perform the task. It can also bundle scripts, reference materials and templates. The name and description sit at the top of the file and tell the AI when the skill is useful, while the rest of the file is plain Markdown that explains how to do the work.
Looking for a SKILL file sample that turns your PRD into an actionable, ready-to-review draft? Check out PRD TO DOCS AI SKILL
The clever part is how the AI reads it. The agent scans the descriptions, and when one matches the current task, the whole skill, including its instructions and supporting files, enters the agent’s context. That means you can keep many skills ready without filling every conversation with instructions the AI doesn’t need yet, and the right one loads only when you ask for that kind of work.
Skill files also aren’t tied to one tool anymore. Anthropic shipped skills in October 2025 and published the format as an open standard on December 18, 2025, and the official showcase now lists more than 40 tools that support it, including GitHub Copilot, VS Code, Cursor, Gemini CLI and OpenAI’s Codex. So a skill you write once can work in whichever AI tool your team happens to use.
The easiest way I’ve found to explain the difference between a prompt and a skill file is to think about onboarding.
A prompt is like explaining a task to a new teammate in a quick chat, which works once but is gone the next day.
A skill file is the onboarding document you hand them on day one, with your style rules, your templates and a checklist for what good work looks like, so every task they do after that starts from the same place.
Why technical writers are the right people to write them
When you look closely at a skill file, it’s really documentation, except the reader is an AI that follows every word it has.
Most of the skills of a good skill file are skills we already use at work:
- Structure: We know how to turn messy information into a clear structure, which is exactly what a skill needs. Style guides, templates and information architecture are part of our daily work, and frameworks like Diátaxis already teach us that a how-to guide and a feature overview need different structures.
- Clear language: We’re trained to remove ambiguity, because ambiguous instructions confuse AI in the same way they confuse users. A rule like “keep it consistent” means nothing to an AI. A rule like “use sentence case for headings and bold only UI labels” produces the same result every time.
- Defined terms: We define terms before we use them, which stops the AI from inventing its own names for your features.
- Knowing what good output looks like: We already review docs every day, so we know how to tell when a draft is right. A skill without a final checklist will happily produce confident drafts that are wrong, and writing that checklist comes naturally to someone who reviews documentation for a living.
- Knowing the workflow: We sit between product, engineering and support, so we know the full path a feature takes from a PRD to release notes. Engineers are writing excellent skills for coding tasks, but a skill for documentation needs someone who understands what users need from the docs and where they usually get stuck.
What a good skill file changes in your day
The biggest change for me was how much repeated manual work disappeared. Before I used skills, a lot of my time went into pasting the same style rules, correcting product names, rebuilding page structures and reformatting release notes into our five standard sections. Once those rules lived in one skill file, I stopped fixing them by hand, because every draft started from the same instructions.
The second change was consistency across the team. When every writer uses the same skill, drafts from different people come back with the same structure, the same terms and the same tone. Reviews get faster as a result, because the reviewer is checking facts instead of formatting.
I want to be honest about what a skill file doesn’t change, though. The AI still writes the first draft, and you still have to check every field, every default and every step against the real product before anything ships. A good skill makes that checking easier, because the drafts are predictable and the open questions are listed up front, but it doesn’t remove the need for a writer who knows the product.
From one PRD to five consistent drafts
The task where a skill file has saved me the most time is turning a product requirements document into docs. When a PRD lands, the usual routine is to read it a few times, list the questions for the product manager, wait for answers, and then write the feature overview, the how-to guide and the release notes one by one. Each of those pages follows rules your team has agreed on, and every one of those rules is something the AI has to be told.
So I packaged the skill I use for this into a product called the PRD to Docs AI Skill You give the AI a PRD, and the skill produces five drafts that follow the same structure every time:
- A questions log: This lists the few questions that decide whether the docs are correct, with the assumption taken for each one, so you can start writing before the PM replies.
- A glossary: It gives one plain definition for every new term.
- A feature overview: It explains what the feature does and who can use it.
- A how-to guide: It covers the main task from start to finish.
- Release notes: These are split into What’s new, What’s enhanced, What’s changed, Deprecated and Removed.
The questions log is my favourite part. In my experience, a wrong assumption costs more time than a slow draft, and seeing the risky assumptions listed before any writing starts changes how the whole review goes.
To make the skill yours, you fill in a few settings and a short profile of your company, such as your product names and your voice. From then on, every draft reads like your docs instead of generic AI output. The package includes the full SKILL.md file, a finished example company profile, a ZIP ready to upload to Claude and a 24-page setup guide. It works best in Claude and Claude Code, and you can paste the same instructions into other AI tools too.
How to start writing your own skill file
You don’t need my skill to get started, and I’d encourage every technical writer to try writing one, because it’s quickly becoming part of the job. These steps are a good place to begin:
- Pick one recurring task: Release notes work well, because they follow the same format every time and take more time than they should.
- Write down what good looks like: Add one real example your team approved, so the AI has a model to match instead of guessing.
- Turn every preference into a specific rule: Replace adjectives like “clear” or “consistent” with instructions the AI can follow exactly.
- Add a final checklist: List what the AI must confirm before it hands you the draft, such as product names, headings and section order.
- Test it on two or three real inputs: When a draft comes back wrong, fix the skill instead of the draft, so the same mistake doesn’t come back next time.
Conclusion
AI can write first drafts faster than any of us, but it still needs someone to tell it what good documentation looks like. That person should be the technical writer. We already know the structure, the rules, the terms and the checks, and a skill file is just the place where all of that finally gets written down for a new kind of reader.
If you’d like a working example to learn from or build on, the PRD to Docs AI Skill is a good starting point. Either way, I’d love to know whether you’ve written a skill file for your docs work yet, and which task you would automate first. Tell me in the comments.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.