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,
Install
npx skills add pproenca/dot-skills --skill diataxisgit 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/diataxisPersonal 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.
Details
- Skill name
diataxis- Repository
- pproenca/dot-skills
- 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
228pproenca/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.
37signals Rails
228pproenca/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.
Acceptance Pipeline Catalog
228pproenca/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.
Docs Search
228pproenca/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
Dev Rfc
228pproenca/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
Drafting
191jwynia/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.
Browse the most popular Claude skills, all writing & content skills, or write your own with the skills generator.