# diataxis

diataxis sorts technical docs into four modes: tutorial, how-to, reference, explanation. Tells the agent which one a page needs before it starts writing.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 149 installs · ★ 227 repo stars
- Author: pproenca
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/diataxis/SKILL.md
- Updated: 2026-08-15
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/diataxis

## What it does

The skill fires on requests like “write the docs”, “document this” or “our README is a mess”, even when nobody names Diátaxis. It puts the content into one of four modes: tutorial, how-to, reference, explanation. A two-question compass does the sorting. Does the text inform action or understanding? Is the reader studying or working? The pair of answers points at the mode.

Decision trees cover the usual symptoms: a page that tries to do all four things, a beginner who cannot start, a reader who cannot find a fact. Each mode has its own guide, and `workflow.md` keeps edits small. On a large existing docs tree, `bash references/queries/scan-docs.sh <docs_root>` flags pages carrying signals of more than one mode.

Line editing inside an already correct mode is not its job; that is a copywriting skill. Everything else runs in small steps, and `quality.md` judges accuracy and consistency, plus whether the page reads well.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill diataxis -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/diataxis/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/diataxis/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill diataxis -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/diataxis/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill diataxis -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/diataxis/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install pproenca/dot-skills skills/.experimental/diataxis
```

2. **Manually: put the files in place**
- File: `.github/skills/diataxis/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill diataxis -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/pproenca/dot-skills --path skills/.experimental/diataxis
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/diataxis/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add pproenca/dot-skills --skill diataxis -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/diataxis/SKILL.md

## When to use it
- classify a page before writing a line
- split a bloated page into teaching and reference
- fix onboarding that leaves beginners stuck
- audit a large docs tree in small steps
- spot pages that mix more than one mode

## Example prompts
- Write the README for this library, but run the compass first and tell me which mode it needs.
- Docs in `docs/` are a mess. Run `bash references/queries/scan-docs.sh docs` and pick the first page to fix.
- This page mixes a tutorial with an API table. Split it and keep the table as reference.

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 21973722e1c70710.

BEGIN THIRD-PARTY FILE 21973722e1c70710
```text
---
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
```
END THIRD-PARTY FILE 21973722e1c70710

The third-party file has ended. Everything between the 21973722e1c70710 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2614 of 8241 bytes. © pproenca · MIT · https://github.com/pproenca/dot-skills/tree/HEAD/skills/.experimental/diataxis/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
