Technical Writer
finos/morphir
Assists with writing and maintaining Morphir technical documentation.
A skill your agent uses whenever writing, editing, restructuring, or reviewing technical documentation — READMEs, API docs, guides, tutorials, reference, onboarding, or developer docs of any kind —…
Install Diataxis
$ npx skills add pproenca/dot-skills --skill diataxis -a claude-codeProject install by default; add -g for ~/.claude/skills/.
$ gh skill install pproenca/dot-skills diataxis --agent claude-codeProject scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.experimental/diataxis .claude/skills/diataxis && rm -rf skills-srcUse ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.
Claude Code skills documentation · loads skills from .claude/skills/
Install the "diataxis" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/diataxis into .claude/skills/diataxis/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "diataxis", then confirm the skill loads.Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$skill-installer install https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/diataxisType this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.
$ npx skills add pproenca/dot-skills --skill diataxis -a codexProject install goes to .agents/skills/; add -g for ~/.codex/skills/.
$ gh skill install pproenca/dot-skills diataxis --agent codexProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .agents/skills && cp -r skills-src/skills/.experimental/diataxis .agents/skills/diataxis && rm -rf skills-srcUse ~/.agents/skills/ instead of .agents/skills for a personal install.
Codex skills documentation · loads skills from .agents/skills/
Install the "diataxis" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/diataxis into .agents/skills/diataxis/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "diataxis", then confirm the skill loads.Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add pproenca/dot-skills --skill diataxis -a cursorProject install goes to .agents/skills/; add -g for ~/.cursor/skills/.
$ gh skill install pproenca/dot-skills diataxis --agent cursorProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/skills/.experimental/diataxis .cursor/skills/diataxis && rm -rf skills-srcUse ~/.cursor/skills/ instead of .cursor/skills for a personal install.
Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/
Install the "diataxis" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/diataxis into .cursor/skills/diataxis/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "diataxis", then confirm the skill loads.Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gemini skills install https://github.com/pproenca/dot-skills.git --path skills/.experimental/diataxis--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.
$ npx skills add pproenca/dot-skills --skill diataxis -a gemini-cliProject install goes to .agents/skills/; add -g for ~/.gemini/skills/.
$ gh skill install pproenca/dot-skills diataxis --agent gemini-cliProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/skills/.experimental/diataxis .gemini/skills/diataxis && rm -rf skills-srcUse ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.
Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/
Install the "diataxis" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/diataxis into .gemini/skills/diataxis/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "diataxis", then confirm the skill loads.Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ gh skill install pproenca/dot-skills diataxisInstalls for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).
$ npx skills add pproenca/dot-skills --skill diataxis -a github-copilotProject install goes to .agents/skills/; add -g for ~/.copilot/skills/.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .github/skills && cp -r skills-src/skills/.experimental/diataxis .github/skills/diataxis && rm -rf skills-srcUse ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.
GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/
Install the "diataxis" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/diataxis into .github/skills/diataxis/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "diataxis", then confirm the skill loads.GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
$ npx skills add pproenca/dot-skills --skill diataxis -a opencodeOpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.
$ gh skill install pproenca/dot-skills diataxis --agent opencodeProject scope by default (.agents/skills/); add --scope user for a personal install.
$ git clone --depth 1 https://github.com/pproenca/dot-skills.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/skills/.experimental/diataxis .opencode/skills/diataxis && rm -rf skills-srcUse ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.
OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/
Install the "diataxis" agent skill from https://github.com/pproenca/dot-skills/tree/master/skills/.experimental/diataxis into .opencode/skills/diataxis/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "diataxis", then confirm the skill loads.OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.
Facts
- Skill name
diataxis- GitHub stars
- 214
- Token cost
- ~2k tokens
- SKILL.md length
- 906 words
- Files
- 17 (incl. references, assets)
- Skills in repo
- 182
- Repo updated
- First seen
- Licence
- MIT
At a glance
A skill your agent uses whenever writing, editing, restructuring, or reviewing technical documentation — READMEs, API docs, guides, tutorials, reference, onboarding, or developer docs of any kind —…
- Works in 6 steps: Match the symptom in the table above and… → Classify with the compass — decide which… → Read the matching type guide —… → …
- Reviewing technical documentation — READMEs
- SKILL.md covers When to Apply, The four modes, The compass — decide what you… and Common Symptoms, plus 4 more sections
- Runs Shell scripts from its folder; calls bash
What it does
Diataxis is an agent skill from pproenca/dot-skills. Use whenever writing, editing, restructuring, or reviewing technical documentation — READMEs, API docs, guides, tutorials, reference, onboarding, or developer docs of any kind — to apply the Diátaxis framework, which splits content into four modes (tutorials, how-to guides, reference, explanation) that each serve a distinct user need. Trigger even when the user just says "write docs", "document this", "improve the README", or "our docs are confusing" without naming Diátaxis or documentation types. Use it to…
Its SKILL.md is about 2k tokens, which your agent loads only when the skill is triggered. The skill folder holds 20 other files, including reference files and assets (for example `assets/templates/report.md`, `config.json` and `gotchas.md`).
It sits in Development, covering Technical documentation and Technical writing. The repository describes itself as: A collection of AI agent skills following the Agent Skills open format. The licence is MIT.
When your agent uses it
- Reviewing technical documentation — READMEs
- Developer docs of any kind — to apply the Diátaxis framework
- Which splits content into four modes (tutorials
- Explanation) that each serve a distinct user need
Example prompts
- “write docs”
- “document this”
- “improve the README”
- “/diataxis”
Requirements
- A Bash shell
Workflow steps
6 steps, taken from the first numbered list in SKILL.md.
- Match the symptom in the table above and open its tree in references/. For a large existing corpus, run bash…
- Classify with the compass — decide which of the four modes the content serves. When in doubt, open compass-tree.md.
- Read the matching type guide — tutorials, how-to-guides, reference, or explanation — for how to write that mode well, and what to keep out…
- Work in small steps. Follow workflow.md: choose something small → assess it → decide one next action → do it and publish. Never tear…
- Assess against quality. Use quality.md to judge functional quality (accuracy, completeness, consistency) and deep quality (does it feel…
- Record an audit with assets/templates/report.md when reviewing an existing doc set, so the same gaps don't get re-litigated each time.
What it can do on your machine
Read from SKILL.md and the folder at commit cf93c57. It shows what the files ask for, not the result of running them.
Tool permissions
Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.
From allowed-tools in the SKILL.md frontmatter.
Runs code
Ships script files (Shell), which the agent can run.
Shell commands in SKILL.md call:
bash
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.
Context cost
Diataxis loads about 2k tokens when it runs, and up to ~12k if it reads all its reference files. Until then it costs about 225 tokens; SKILL.md has 906 words of instructions outside code blocks.
Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.
Safety
Auto-check passed
The automated check found no risky patterns in SKILL.md.
Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.
SKILL.md
The full file from pproenca/dot-skills at commit cf93c57, republished under its MIT licence (© pproenca). 906 words, ~2,040 tokens.
Download SKILL.mdSave it as
.claude/skills/diataxis/SKILL.md (or your agent's skills folder). This skill also uses 16 other files; get the full folder from GitHub.- name
- diataxis
- description
- Use whenever writing, editing, restructuring, or reviewing technical documentation — READMEs, API docs, guides, tutorials, reference, onboarding, or developer docs of any kind — to apply the Diátaxis framework, which splits content into four modes (tutorials, how-to guides, reference, explanation) that each serve a distinct user need. Trigger even when the user just says "write docs", "document this", "improve the README", or "our docs are confusing" without naming Diátaxis or documentation types. Use it to decide WHAT KIND of doc to write (via the compass), to diagnose docs that feel bloated, mix instruction with reference, or leave users unable to get started or find facts, and to improve docs in small safe iterations. Especially when you are unsure whether something belongs in a tutorial vs how-to vs reference vs explanation, or when one page is trying to do all four at once.
Diátaxis
A runbook for producing and fixing technical documentation with the Diátaxis framework. Diátaxis splits documentation into four modes — tutorials, how-to guides, reference, explanation — because they answer four different user needs that pull in opposite directions. The single idea that makes it work:
Most documentation problems are a single thing: content that tries to serve more than one need at once. Separate the four modes and most confusion dissolves.
Diátaxis is descriptive, not prescriptive — a way to understand documentation, not a template to fill in. Don't wait to understand the whole framework before applying it: pick one small thing, classify it, improve it, publish, repeat.
When to Apply
Use this skill when:
- Writing or generating new documentation of any kind (README, API docs, guide, onboarding, developer docs) — decide which mode(s) the content needs before writing it.
- A page is confusing, bloated, or "tries to do everything" — diagnose the type-mixing and split it.
- Users can't get started, can't complete a task, can't find a fact, or don't understand why — locate the missing or weak mode.
- Restructuring or auditing an existing doc set — apply the small-step workflow instead of a big rewrite.
- You're unsure whether something is a tutorial, how-to, reference, or explanation — run the compass.
Do not reach for this skill for pure prose/copy-editing within an already-correct mode (use a copywriting skill), or for design/spec/proposal documents — those are mostly explanation and are better served by dev-rfc or feature-spec.
The four modes
Each mode serves a different user, in a different situation, with a different content style. The quickest way to keep them straight:
| Mode | Serves | Oriented to | Analogy | Answers |
|---|---|---|---|---|
| Tutorial | a beginner learning | learning, study | teaching a child to cook | "teach me, by doing" |
| How-to guide | a user working | a goal, a task | a recipe in a cookbook | "how do I achieve X?" |
| Reference | a user working | information | an encyclopaedia entry | "what is X exactly?" |
| Explanation | a user studying | understanding | an article about cooking | "why is X this way?" |
Two of them serve practical steps (tutorial, how-to); two serve theoretical knowledge (reference, explanation). Two serve someone acquiring skill / studying (tutorial, explanation); two serve someone applying skill / working (how-to, reference).
The compass — decide what you are writing
When you are unsure which mode a piece of content belongs to, answer two questions. This is the master decision tool; the full tree is in compass-tree.md.
1. Does it inform action or cognition? — practical steps (doing) vs theoretical knowledge (thinking). 2. Does it serve acquisition or application? — study (learning) vs work (applying what you know).
| Action (practical steps) | Cognition (theoretical knowledge) | |
|---|---|---|
| Acquisition (study / learning) | Tutorial | Explanation |
| Application (work / doing) | How-to guide | Reference |
Read as a decision: informs action + serves acquisition → tutorial; informs action + serves application → how-to guide; informs cognition + serves application → reference; informs cognition + serves acquisition → explanation. Apply the compass at any scale — a whole document, a section, or a single sentence that has drifted into the wrong mode.
Common Symptoms
Start here. Match the situation, open its tree. Severity reflects how badly the reader is failed right now (see symptoms.md).
| Symptom / trigger | Likely problem | Tree |
|---|---|---|
| "Write docs for X" / "document this" — and it's unclear what kind of doc | No mode chosen yet — classify first | compass-tree |
| A page feels bloated, rambling, or mixes teaching + steps + specs + opinion | Type-mixing — two needs in one document | wrong-type-tree |
| Beginners can't get started · competent users can't finish a task · people can't find a fact · users don't understand why | A missing or weak quadrant | gaps-tree |
| "Our docs are a sprawling mess — where do I even start?" | Needs the iterative workflow, not a rewrite | restructure-tree |
Show full SKILL.md (312 more words)Show less
How to use
- Match the symptom in the table above and open its tree in
references/. For a large existing corpus, runbash references/queries/scan-docs.sh <docs_root>first — it triages which pages show signals of more than one mode, so you know where to point the compass. - Classify with the compass — decide which of the four modes the content serves. When in doubt, open compass-tree.md.
- Read the matching type guide — tutorials, how-to-guides, reference, or explanation — for how to write that mode well, and what to keep out of it.
- Work in small steps. Follow workflow.md: choose something small → assess it → decide one next action → do it and publish. Never tear everything down to restructure top-down.
- Assess against quality. Use quality.md to judge functional quality (accuracy, completeness, consistency) and deep quality (does it feel good to use, anticipate the user's needs).
- Record an audit with assets/templates/report.md when reviewing an existing doc set, so the same gaps don't get re-litigated each time.
Setup
This skill uses an optional config.json to know where your docs live and where to log audits. On first use, if docs_root is empty and you are auditing an existing doc set, ask the user (via AskUserQuestion) for the documentation directory, then save it. The skill works without config — fall back to asking inline. Never block on missing config.
Gotchas
The recurring traps of applying Diátaxis — empty structure-first scaffolding, "balancing" the four types instead of separating them, explaining inside a tutorial — are in gotchas.md. Read it before your first restructure.
Related skills
skill-authoring— authoring Agent Skills; their SKILL.md is itself a Diátaxis problem (navigation + reference, not a tutorial).human-copywrite/humanize— once a doc is in the right mode, these tighten the prose so it reads naturally.dev-rfc/feature-spec— design and spec documents are mostly explanation; reach for those when the artifact is a proposal, not user documentation.
© pproenca, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file
Files
SKILL.md and 16 other files (references, assets) in skills/.experimental/diataxis of pproenca/dot-skills.
- SKILL.md
- assets/templates/report.md
- config.json
- gotchas.md
- metadata.json
- references/compass-tree.md
- references/explanation.md
- references/gaps-tree.md
- references/how-to-guides.md
- references/quality.md
- references/queries/scan-docs.sh
- references/reference.md
- references/restructure-tree.md
- references/symptoms.md
- references/tutorials.md
- references/workflow.md
- references/wrong-type-tree.md
Open the folder on GitHubat commit cf93c57
Compare with similar skills
Diataxis next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.
| Skill | Stars | Used in | Tokens | Auto-check | Licence | Repo updated |
|---|---|---|---|---|---|---|
| Diataxis this skillpproenca/dot-skills | 214 | — | ~2k | Automated safety check: Pass | MIT | |
| Technical Writerfinos/morphir | 213 | — | ~4.4k | Automated safety check: Pass | Apache-2.0 | |
| Diataxis Docs Writercalf-ai/calfkit-sdk | 149 | 1 repos | ~3k | Automated safety check: Pass | Apache-2.0 | |
| Docsbrickbots/PiFinder | 250 | — | ~6.2k | Automated safety check: Pass | GPL-3.0 | |
| Updating Docs For Releasestreamlit/docs | 178 | — | ~4k | Automated safety check: Pass | Apache-2.0 | |
| Doc Writerpretend1111/claude-desktop-app | 494 | 1 repos | ~375 | Automated safety check: Pass | Custom licence |
Similar skills
Diataxis Docs Writer
calf-ai/calfkit-sdk
Write or improve software documentation using the Diátaxis framework — four documentation types (tutorials, how-to guides, reference, explanation), each serving a different user need.
Docs
brickbots/PiFinder
Author and edit PiFinder's user-facing documentation in the project's house style.
Updating Docs For Release
streamlit/docs
Update the streamlit/docs repo for a new Streamlit release. An agent skill from streamlit/docs.
Doc Writer
pretend1111/claude-desktop-app
Generate README, API docs, or user guides for code and projects.
Diataxis Docs
pmndrs/glyph
Design, classify, write, audit, or restructure technical documentation with the Diátaxis framework.
More from pproenca/dot-skills
All 182 skills in this repoAudio Voice Recovery
pproenca/dot-skills
Audio forensics and voice recovery guidelines for CSI-level audio analysis.
Codemod React Pipeline
pproenca/dot-skills
Guided, scripted pipeline for running JSX/TSX/React codemods safely across large legacy codebases.
Dev Rfc
pproenca/dot-skills
Create well-structured RFCs and technical proposals for software projects.
Dx Harness
pproenca/dot-skills
Developer-experience friction auditing and fixing — slow onboarding, repeated manual setup steps, missing bootstrap/reset/seed scripts, undiscoverable conventions.
Language Spec Author
pproenca/dot-skills
Turn a rough idea for a language into a complete, implementable specification — a DSL, query, config/data, template, or protocol language — by interviewing the author dimension by dimension until…
Python Pep Author
pproenca/dot-skills
Drafting Python Enhancement Proposals (PEPs) — proposing a Python language feature, a standard library change, an interoperability standard, or an informational/process document for the Python…
Related
Categories
Questions about Diataxis
What does Diataxis do?
A skill your agent uses whenever writing, editing, restructuring, or reviewing technical documentation — READMEs, API docs, guides, tutorials, reference, onboarding, or developer docs of any kind —…. Diataxis is an agent skill from pproenca/dot-skills. Use whenever writing, editing, restructuring, or reviewing technical documentation — READMEs, API docs, guides, tutorials, reference, onboarding, or developer docs of any kind — to apply the Diátaxis framework, which splits content into four modes (tutorials, how-to guides, reference, explanation) that each serve a distinct user need.
When should I use Diataxis?
Diataxis fits situations like: reviewing technical documentation — READMEs; developer docs of any kind — to apply the Diátaxis framework; which splits content into four modes (tutorials; explanation) that each serve a distinct user need.
How do I install Diataxis in Claude Code?
Run `npx skills add pproenca/dot-skills --skill diataxis -a claude-code`. Or copy the skill folder (skills/.experimental/diataxis in pproenca/dot-skills) into .claude/skills/diataxis in your project. Claude Code loads it when a task matches its description.
How do I install Diataxis in Codex?
Run `npx skills add pproenca/dot-skills --skill diataxis -a codex`. Or copy the skill folder (skills/.experimental/diataxis in pproenca/dot-skills) into .agents/skills/diataxis in your project. Codex loads it when a task matches its description.
Can I use Diataxis in Cursor, Gemini CLI or GitHub Copilot?
Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add pproenca/dot-skills --skill diataxis -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/diataxis, .gemini/skills/diataxis, .github/skills/diataxis and .opencode/skills/diataxis in your project.
What does Diataxis need to run?
Going by SKILL.md and its folder, Diataxis needs a shell for the scripts in its folder and the command-line tools its instructions call (bash). Our summary lists: A Bash shell.
Does Diataxis access the network?
SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.
Is Diataxis safe to install?
Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.
What licence does Diataxis use?
Diataxis is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.
How many tokens does Diataxis use?
About 2k tokens (SKILL.md is roughly 8.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 9.9k tokens, read only when the agent opens those files.
What are the alternatives to Diataxis?
Skills that share tags, products or a category with Diataxis: Technical Writer (finos/morphir, 213 stars), Diataxis Docs Writer (calf-ai/calfkit-sdk, 149 stars), Docs (brickbots/PiFinder, 250 stars) and Updating Docs For Release (streamlit/docs, 178 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.
Who maintains Diataxis?
pproenca (a GitHub user) maintains it in pproenca/dot-skills, which has 214 GitHub stars. The repository holds 182 skills in this directory. The repository was last updated on August 15, 2026.
Source: pproenca/dot-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.