Diataxis

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,

228 stars 19 forksWriting & Content

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add pproenca/dot-skills --skill diataxis
Manual install
git clone --depth 1 https://github.com/pproenca/dot-skills.git /tmp/dot-skills
mkdir -p ~/.claude/skills
cp -r /tmp/dot-skills/skills/.experimental/diataxis ~/.claude/skills/diataxis

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# 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.
Read the full skill on GitHub

Details

Skill name
diataxis
Path
skills/.experimental/diataxis/SKILL.md
License
MIT
Repo updated
15 August 2026

FAQ

What does the Diataxis skill do?

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,

How do I install the Diataxis skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add pproenca/dot-skills --skill diataxis. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is Diataxis popular?

It lives in pproenca/dot-skills, which has 228 GitHub stars and 19 forks.

Related skills

12 Factor App

228

pproenca/dot-skills

The Twelve-Factor App methodology for building scalable, maintainable cloud-native applications. Use when designing backend services, APIs, microservices, or any software-as-a-service application. Triggers on deployment patterns, configuration management, process architecture, logging, and infrastructure decisions.

Software Development19

37signals Rails

228

pproenca/dot-skills

37signals Rails coding principles and conventions from DHH, Jorge Manrubia, and the Fizzy/Basecamp/HEY codebase. This skill should be used when writing, reviewing, or refactoring Ruby on Rails code following the 37signals philosophy — vanilla Rails, CRUD controllers, rich domain models, concerns, no service objects, Hotwire, Turbo, Stimulus, Solid Queue, Solid Cache, Solid Cable, multi-tenancy, Minitest, custom auth, or DHH conventions.

Software Development19

Acceptance Pipeline Catalog

228

pproenca/dot-skills

Use when implementing, reviewing, or debugging a Gherkin acceptance-test pipeline with mutation testing. Covers parser, JSON IR, generator, runtime, step handlers, test runner, mutator, value mutation rules, execution, result classification, reporting, project layout, conformance, and agent setup. Based on Uncle Bob's Acceptance Pipeline Specification. Trigger even when the user mentions Gherkin parsing, acceptance test generation, mutation testing for acceptance tests, or building a portable test pipeline.

Testing & QA19

Docs Search

228

pproenca/dot-skills

Library-documentation lookup methodology — API behavior, version-specific changes, idiomatic usage, or why production diverges from docs — independent of which library. Distills the generic navigation moves shared across libraries — classify the question before searching (changelog vs API reference vs idiom vs known-bug), check llms.txt before scraping HTML, pin to the user's version before reading reference pages, read changelog first for "did X change" questions, treat examples/ dirs as truth for idioms, and fall back to GitHub issues / status page / Discord when docs match but reality doesn

Writing & Content19

Dev Rfc

228

pproenca/dot-skills

Create well-structured RFCs and technical proposals for software projects. Use this skill whenever the user wants to write an RFC, technical proposal, design doc, architecture doc, or system design overview. Also trigger when the user says things like "write an RFC", "I need to propose a new system", "create a technical proposal", "document the architecture", "write up the design", "I need a design doc", or "explain the system architecture in a doc". Even if they just say "RFC", "design doc", or "arch doc", use this skill. Covers both RFCs (proposing what to build) and architecture docs (docum

Writing & Content19

Drafting

191

jwynia/agent-skills

Break through blocks and execute first drafts. Use when the outline is done but the draft isn't happening, when writer's block strikes, when the blank page remains blank, or when progress stalls.

Writing & Content24

Browse the most popular Claude skills, all writing & content skills, or write your own with the skills generator.