skills.rest
alunduil
alunduilCOMMUNITY
Explore all skills by this author →
Website𝕏@alunduilGitHub

diataxis

Classify documentation artifacts into Diátaxis modes and enforce mode-specific writing rules.

1|2|Updated Apr 23, 2026
Search Tags:#documentation#reference#how-to#explanation#tutorial#diataxis#content-writing
One-click install
npx skills add https://github.com/alunduil/alunduil-chezmoi --skill diataxis-alunduil
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: diataxis
Source: https://github.com/alunduil/alunduil-chezmoi/tree/main/dot_claude/skills/diataxis
Command: npx skills add https://github.com/alunduil/alunduil-chezmoi --skill diataxis-alunduil

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Audit, write, or revise docs under docs/ (or repo equivalent) when the artifact is a tutorial, how-to, reference, or explanation — anything not already a README, CONTRIBUTING, ADR, or CHANGELOG. Forces a Diátaxis mode pick before writing, then loads mode-specific anti-patterns. Use when creating or editing a tutorial/how-to/reference/explanation doc, or when prose drifts across modes (the canonical case: a how-to growing explanatory paragraphs).

Core Features & Use Cases

  • Guide content classification and mode selection to align artifacts with Tutorial, How-to, Reference, and Explanation types.
  • Enforce mode-specific writing rules and anti-patterns to improve clarity and consistency across documentation.
  • Provide a safe fallback when a document would otherwise drift between modes, ensuring a single-mode approach per document.

Quick Start

Specify the target Diátaxis mode for the document (Tutorial, How-to, Reference, or Explanation) before writing, and draft the document in that mode.

Frequently Asked Questions about diataxis

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I structure documentation using the Diátaxis framework?▼

To structure documentation using the Diátaxis framework, you classify content into four distinct modes: tutorials, how-to guides, references, and explanations. You must select a single mode before writing and apply mode-specific rules to maintain consistent, focused content.

What is the best way to fix a how-to guide that contains explanatory paragraphs?▼

Fixing a how-to guide with explanatory paragraphs requires identifying prose drift between documentation modes. You resolve this by isolating the explanatory content into a dedicated explanation document and keeping the how-to strictly action-oriented.

When should I write a tutorial instead of a how-to guide for my repository docs?▼

Write a tutorial instead of a how-to guide when your documentation goal is learning rather than achieving a specific task. Tutorials guide users through safe learning experiences, while how-tos provide direct steps to solve immediate problems.

How do I audit existing repository documentation for mode consistency?▼

Audit repository documentation for mode consistency by reviewing artifacts under docs/ and checking if the prose drifts across tutorial, how-to, reference, or explanation modes. Refactor mixed documents to enforce a single-mode approach per file.

Can I use Diátaxis documentation modes for files other than README and CHANGELOG?▼

Yes, you use Diátaxis documentation modes for any repository artifact that is not already a README, CONTRIBUTING, ADR, or CHANGELOG. This includes drafting or revising any tutorial, how-to, reference, or explanation document.

Related Skills

Explore More Education & Research Skills→
chieflatifchieflatif
2

vibeos-discover

Identify project context and create discovery artifacts from existing code and docs.

Community
Intermediate
wodsmithwodsmith
2

documentation

Generate Diataxis-compliant documentation guidance across four documentation types.

Official
Advanced
abhishekmmgnabhishekmmgn

document-release

Audit project docs against a diff and update key documentation files.

Community
Advanced
ghalacticghalactic
2

diataxis

Classify technical documentation into tutorials, guides, references, and explainers.

Official
Intermediate