Guide · Agent skill
How to use the Diátaxis Documentation Writer agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Diátaxis Documentation Writer is an agent skill: a SKILL.md instruction file that tells an AI agent to behave like a technical writer trained on the Diátaxis framework. This guide explains what the skill changes, how to install it, how to ask for documentation in a way that triggers it, and what to expect from its process. By the end you will be able to add the skill to your agent and get a structured Markdown document built around one of the four Diátaxis document types.
Diátaxis Documentation Writergithub/awesome-copilot · MIT Download the skill Quick start
- 1Download the skill. Download the ZIP of the documentation-writer skill from this page and unzip it. It contains SKILL.md.
- 2Place the folder. Copy the folder into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one repository.
- 3Or upload it in the Claude apps. In the Claude apps, open Settings → Capabilities → Skills and upload the skill.
- 4Make a documentation request. Describe the document you need, its audience and what the reader should achieve.
- 5Answer the clarifying questions. Confirm the document type, audience, goal and scope the agent asks about.
- 6Approve the outline. Review the proposed structure, request changes if needed, then approve it.
- 7Review the Markdown draft. Check the generated document for accuracy, especially commands and technical details, before publishing.
What is the documentation-writer skill and what does it make the agent do?
Agent skills are folders of instructions that an AI agent loads when a task matches them. This one, named documentation-writer, is built around the Diátaxis technical documentation framework (https://diataxis.fr/). Diátaxis sorts documentation into four types: tutorials are learning lessons, how-to guides are recipes for specific problems, reference is factual description of how things work, and explanation discusses concepts.
Once installed, the agent follows a fixed process for documentation requests. It does not start writing straight away.
- Clarify: it determines the document type, target audience, the user's goal, and what is in and out of scope.
- Propose: it offers an outline with brief descriptions and waits for your approval.
- Generate: after you approve the outline, it writes the full document in Markdown.
Install the documentation-writer skill
Download the ZIP of the skill from this page and unzip it. The skill is a single file, SKILL.md. Put the unzipped folder in one of these locations:
- Personal skills for all your projects: ~/.claude/skills/
- Project skills for one repository: a .claude/skills/ folder inside the project
- Claude apps: open Settings → Capabilities → Skills and upload the skill there
How do you trigger the skill with a natural request?
You do not need a special command. Ask the agent for documentation work and say what kind of document you want, who it is for, and what the reader should achieve. The skill's first step is to ask for anything missing, so a short, honest request is enough.
The skill is written for documentation tasks. Requests such as restructuring a project's docs, writing a how-to for a deployment problem, or drafting a reference page for an API are the right fit.
- Write a Diátaxis tutorial that teaches a new contributor to set up the project.
- Restructure our existing docs so tutorials, how-to guides and reference are separated.
- Draft a how-to guide for rotating our API keys, for experienced sysadmins.
- Write an explanation page on why we chose event sourcing.
What happens during a documentation session?
Expect questions before any prose. The agent will try to settle the four items it needs: document type, audience, goal and scope. Answer them clearly; vague answers lead to a vaguer outline.
When the outline arrives, check the sections and what is excluded. Approve it or ask for changes. Only then does the full Markdown document get written.
- If you provide other Markdown files, the agent uses them to learn your project's tone, style and terminology, but it does not copy their content unless you ask.
- The agent may not consult external websites or other sources unless you give it a link and instruct it to do so. Supply any facts it needs.
Safety notes: scripts and network access
The skill's listing states that it runs no scripts and uses no network access. It requires nothing beyond the SKILL.md file. Its instructions tell the agent not to consult outside sources unless you provide a link and an instruction, so external facts should come from you.
Because the skill is a text file, review SKILL.md yourself if you want to see exactly what instructions the agent receives.
Tips for getting better documentation
The skill works best when the input is specific. Give it real material: existing docs, the code or commands you want covered, and the exact reader you have in mind. Name what is out of scope, because the skill asks for that explicitly and it keeps documents focused.
Use the outline step to catch problems early. Changing the structure before drafting is cheaper than rewriting a finished document.
- Name one document type per request. Mixing types is what the framework is designed to prevent.
- Provide accurate commands and technical details. The skill's guiding principles stress accuracy, but it cannot verify facts it has not been given.
- For quick answers or one-line questions, ask the agent directly without the skill; its process is slower by design.
What people use it for
- Writing a Diátaxis tutorial that walks a newcomer through a project's first successful run.
- Writing a how-to guide for a specific operational problem, such as a recurring deployment step.
- Producing a reference page that describes the parts of an API or configuration in factual terms.
- Writing an explanation page that discusses why a system is designed the way it is.
- Restructuring a mixed documentation set so tutorials, guides, reference and explanation are separated.
Frequently asked questions
Is the documentation-writer skill free?
The skill is listed under the MIT licence on the github/awesome-copilot repository. This page does not state any price, so check the source repository for licence terms.
What do I need to use the documentation-writer skill?
The listing says it requires nothing beyond the skill itself. It runs no scripts and uses no network access, and the only file listed is SKILL.md.
Where do I install the documentation-writer skill?
Unzip the downloaded skill and place the folder in ~/.claude/skills/ for personal use or in a project's .claude/skills/ folder. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
What is the Diátaxis framework?
Diátaxis is a documentation framework that sorts content into four types: tutorials, how-to guides, reference and explanation. The skill follows its principles and structure, and the framework's home is https://diataxis.fr/.
Why does the agent ask questions before writing?
The skill requires the agent to determine the document type, audience, goal and scope before proceeding, then propose an outline for your approval. This prevents a document that is aimed at the wrong reader or covers the wrong topics.
Can the skill research current facts or check my commands?
Not on its own. The skill says the agent may not consult external websites or sources unless you provide a link and instruct it to, so you should supply accurate technical details and verify commands yourself.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Choose this skill if you write or restructure project documentation and want a consistent, framework-based process that separates tutorials, guides and reference. Skip it for quick one-line answers, non-documentation tasks, or anything that depends on the agent researching current external facts.
Download the skill