How do I install the Diataxis skill?

Run npx skillmds@latest add joaquimscosta/diataxis in your terminal (requires Node.js), paste this page's agent-chat prompt into Claude, Cursor, or any MCP-connected agent, or download the SKILL.md file and copy it into your agent's skills directory.

Is Diataxis safe to use?

This skill has not completed SkillMD's automated safety review yet. Capability flags: executes scripts, makes network calls. SkillMD never runs a skill's scripts for you; review the SKILL.md before installing.

Which AI agents work with Diataxis?

This skill is tagged as working with Claude Code, Claude.ai, OpenAI Codex. SKILL.md is an open format, so most agents that read a skills directory can load it too.

Is Diataxis free to use?

Yes. Installing skills from SkillMD is free, and the skill stays under its author's original license.

Who published Diataxis?

joaquimscosta (@joaquimscosta) published this skill. Their other Agent Skills are listed on their SkillMD profile.

Diataxis by joaquimscosta — Agent Skill

Name: Diataxis
Rating: 4.666666666666667 (3 reviews)
Author: joaquimscosta

Diataxis

Audit, classify, validate, and scaffold documentation using the Diataxis framework (Tutorials, How-to guides, Reference, Explanation). Use when user mentions "diataxis", "documentation framework", "quadrant", "doc audit", "doc coverage", "collapsed document", "tutorial vs how-to", "quadrant purity", "documentation types", or wants to classify docs by type.

joaquimscosta Updated Sep 10, 2026

File contents

Diataxis Documentation Framework

Audit, classify, validate, and scaffold documentation using the Diataxis framework.

Quick Start

# Classify individual files
uv run scripts/diataxis_classify.py docs/*.md

# Audit a docs directory for coverage
uv run scripts/diataxis_audit.py --dir docs

# Validate quadrant purity
uv run scripts/diataxis_validate.py --dir docs

# Scaffold a new Diataxis structure
uv run scripts/diataxis_scaffold.py --dry-run
uv run scripts/diataxis_scaffold.py

Capabilities

Script	Purpose	Key Flags
`diataxis_classify.py`	Classify files into quadrants	`--json`, `--verbose`, `--no-content`
`diataxis_audit.py`	Coverage report with quality score	`--dir`, `--json`, `--min-coverage`
`diataxis_validate.py`	Lint for quadrant purity (DX001-DX010)	`--dir`, `--file`, `--strict`, `--json`
`diataxis_scaffold.py`	Generate folder structure	`--layout folders\|flat`, `--init-config`, `--dry-run`

The Four Quadrants

Quadrant	Orientation	User State	Folder
Tutorial	Learning	Study + Action	`tutorials/`
How-to	Task	Work + Action	`how-to/`
Reference	Information	Work + Cognition	`reference/`
Explanation	Understanding	Study + Cognition	`explanation/`

Classification Algorithm

Multi-signal weighted scoring (title 30%, headings 25%, content 25%, structure 20%). Documents scoring highly for 2+ quadrants are flagged as "collapsed" with split suggestions.

Validation Rules

ID	Rule	Severity
DX001	Tutorial contains reference tables	warning
DX002	How-to has long conceptual preamble	warning
DX003	Reference contains step-by-step instructions	warning
DX004	Explanation contains execution commands	warning
DX005	No clear quadrant signal	info
DX006	Collapsed document (mixed quadrants)	warning
DX007	Tutorial missing prerequisites	info
DX008	Tutorial missing learning objectives	info
DX009	How-to missing problem statement	info
DX010	Reference missing tables	info

Config File (.diataxis-config.json)

Optional per-project override:

{
  "version": 1,
  "root": "docs",
  "layout": "folders",
  "ignore": ["node_modules", ".git", "adr", "rfcs", "*.pdf"],
  "custom_signals": {}
}

Create with uv run scripts/diataxis_scaffold.py --init-config.

Common Issues

Issue	Fix
`uv` not found	`curl -LsSf https://astral.sh/uv/install.sh \| sh` or run with `python3 scripts/diataxis_classify.py`
Low confidence on all files	Files may lack quadrant-specific keywords; use `--verbose` to inspect scores
Too many collapsed warnings	Some docs legitimately mix quadrants; consider splitting or accepting

See TROUBLESHOOTING.md for all error scenarios.

References

WORKFLOW.md — Full methodology (discover, classify, audit, validate, scaffold)
EXAMPLES.md — Real-world examples for all operations
TROUBLESHOOTING.md — Error handling and debugging tips
Diataxis framework — Official documentation

---name: diataxisdescription: Audit, classify, validate, and scaffold documentation using the Diataxis framework (Tutorials, How-to guides, Reference, Explanation). Use when user mentions "diataxis", "documentation framework", "quadrant", "doc audit", "doc coverage", "collapsed document", "tutorial vs how-to", "quadrant purity", "documentation types", or wants to classify docs by type.---# Diataxis Documentation FrameworkAudit, classify, validate, and scaffold documentation using the [Diataxis](https://diataxis.fr/) framework.## Quick Start```bash# Classify individual filesuv run scripts/diataxis_classify.py docs/*.md# Audit a docs directory for coverageuv run scripts/diataxis_audit.py --dir docs# Validate quadrant purityuv run scripts/diataxis_validate.py --dir docs# Scaffold a new Diataxis structureuv run scripts/diataxis_scaffold.py --dry-runuv run scripts/diataxis_scaffold.py```## Capabilities| Script | Purpose | Key Flags ||--------|---------|-----------|| `diataxis_classify.py` | Classify files into quadrants | `--json`, `--verbose`, `--no-content` || `diataxis_audit.py` | Coverage report with quality score | `--dir`, `--json`, `--min-coverage` || `diataxis_validate.py` | Lint for quadrant purity (DX001-DX010) | `--dir`, `--file`, `--strict`, `--json` || `diataxis_scaffold.py` | Generate folder structure | `--layout folders\|flat`, `--init-config`, `--dry-run` |## The Four Quadrants| Quadrant | Orientation | User State | Folder ||----------|-------------|------------|--------|| **Tutorial** | Learning | Study + Action | `tutorials/` || **How-to** | Task | Work + Action | `how-to/` || **Reference** | Information | Work + Cognition | `reference/` || **Explanation** | Understanding | Study + Cognition | `explanation/` |## Classification AlgorithmMulti-signal weighted scoring (title 30%, headings 25%, content 25%, structure 20%). Documents scoring highly for 2+ quadrants are flagged as "collapsed" with split suggestions.## Validation Rules| ID | Rule | Severity ||----|------|----------|| DX001 | Tutorial contains reference tables | warning || DX002 | How-to has long conceptual preamble | warning || DX003 | Reference contains step-by-step instructions | warning || DX004 | Explanation contains execution commands | warning || DX005 | No clear quadrant signal | info || DX006 | Collapsed document (mixed quadrants) | warning || DX007 | Tutorial missing prerequisites | info || DX008 | Tutorial missing learning objectives | info || DX009 | How-to missing problem statement | info || DX010 | Reference missing tables | info |## Config File (.diataxis-config.json)Optional per-project override:```json{ "version": 1, "root": "docs", "layout": "folders", "ignore": ["node_modules", ".git", "adr", "rfcs", "*.pdf"], "custom_signals": {}}```Create with `uv run scripts/diataxis_scaffold.py --init-config`.## Common Issues| Issue | Fix ||-------|-----|| `uv` not found | `curl -LsSf https://astral.sh/uv/install.sh \| sh` or run with `python3 scripts/diataxis_classify.py` || Low confidence on all files | Files may lack quadrant-specific keywords; use `--verbose` to inspect scores || Too many collapsed warnings | Some docs legitimately mix quadrants; consider splitting or accepting |See [TROUBLESHOOTING.md](TROUBLESHOOTING.md) for all error scenarios.## References- [WORKFLOW.md](WORKFLOW.md) — Full methodology (discover, classify, audit, validate, scaffold)- [EXAMPLES.md](EXAMPLES.md) — Real-world examples for all operations- [TROUBLESHOOTING.md](TROUBLESHOOTING.md) — Error handling and debugging tips- [Diataxis framework](https://diataxis.fr/) — Official documentation

Frequently asked questions