Skip to main content
skill CX Codex

diataxis — Claude Code skill: what it does, how to install

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

MIT 149 installs ★ 227 updated 2026-08-15

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add pproenca/dot-skills --skill diataxis -a claude-code
Open on GitHub

What diataxis 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.

What it helps with

  • 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 for the agent

  • 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.

How to install diataxis

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill diataxis -a claude-code

2Manually: put the files in place

~/.claude/skills/diataxis/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/diataxis/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about diataxis

How do I install diataxis in Claude Code?

Run npx skills add pproenca/dot-skills --skill diataxis -a claude-code. The skill lands at ~/.claude/skills/diataxis/SKILL.md.

What does diataxis do?

It sorts technical documentation into the four Diátaxis modes and points out which one a given page needs. It also flags text where several modes sit side by side.

Does it rewrite my whole docs site?

No. The workflow goes one small slice at a time: assess the slice, take a single action, publish, then repeat.

Source text

SKILL.md · MIT
---
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](references/tutorials.md)** | a beginner *learning* | learning, study | teaching a child to cook | "teach me, by doing" |
| **[How-to guide](references/how-to-guides.md)** | a user *working* | a goal, a task | a recipe in a cookbook | "how do I achieve X?" |
| **[Reference](references/reference.md)** | a user *working* | information | an encyclopaedia entry | "what is X exactly?" |
| **[Explanation](references/explanation.md)** | 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](references/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](references/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](references/compass-tree.md) |
| A page feels bloated, rambling, or mixes teaching + steps + specs + opinion | Type-mixing — two needs in one document | [wrong-type-tree](references/wrong-type-tree.md) |
| 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](references/gaps-tree.md) |
| "Our docs are a sprawling mess — where do I even start?" | Needs the iterative workflow, not a rewrite | [restructure-tree](references/restructure-tree.md) |

## How to use

1. **Match the symptom** in the table above and open its tree in `references/`. For a large *existing* corpus, run `bash 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.
2. **Classify with the compass** — decide which of the four modes the content serves. When in doubt, open [compass-tree.md](references/compass-tree.md).
3. **Read the matching type guide** — [tutorials](references/tutorials.md), [how-to-guides](references/how-to-guides.md), [reference](references/reference.md), or [explanation](references/explanation.md) — for how to write *that* mode well, and what to keep out of it.
4. **Work in small steps.** Follow [workflow.md](references/workflow.md): choose something small → assess it → decide one next action → do it and publish. Never tear everything down to restructure top-down.
5. **Assess against quality.** Use [quality.md](references/quality.md) to judge functional quality (accuracy, completeness, consistency) and deep quality (does it feel good to use, anticipate the user's needs).
6. **Record an audit** with [assets/templates/report.md](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](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 · pproenca/dot-skills

Similar skills

All skills for Writing and docs →

From the same set139

The whole set →
complexity-optimizer complexity-optimizer detects algorithmic complexity bottlenecks in codebases and suggests safe runtime optimizations. CX Codex +1 156installs nextjs-bundle-optimizer nextjs-bundle-optimizer measures Next.js bundle size and build time, then checks optimizations one change at a time. Useful when First Load JS grows or production builds slow down. CX Codex +1 152installs implementation-design-patterns implementation-design-patterns is a Claude Code skill that identifies a Gang of Four pattern from a problem description and explains when to apply or avoid it. CX Codex +1 151installs better-auth A TypeScript skill for Better Auth: instance setup, adapter choice, sessions and cookies, plugins, plus migration from another auth library. CX Codex +1 150installs drizzle-sqlite-scaffold drizzle-sqlite-scaffold generates boilerplate for Drizzle ORM + SQLite: config, client with pragmas, table schemas, CRUD modules and validators. Triggers on phrases like “add a table for X” or “set up the DB”. CX Codex +1 149installs same-results-less-code The same-results-less-code skill helps spot conceptual complexity during code review and refactoring while preserving behavior. It looks beyond the mechanical issues linters catch. CX Codex +1 148installs codebase-comprehension-algorithms codebase-comprehension-algorithms maps an unfamiliar repository into feature domains: which files back a feature, where the architecture actually sits. CX Codex +1 148installs storybook This skill guides Storybook setup and story authoring for TypeScript/React components. Use it for interaction tests, accessibility checks, and component documentation. CX Codex +1 145installs

Project sponsors

Companies that keep this analytics open