From ef01a51d27e6cec90c6801d65f2c891a3ed92a58 Mon Sep 17 00:00:00 2001 From: Ertem Biyik Date: Mon, 9 Feb 2026 13:31:06 +0800 Subject: [PATCH] Add diataxis skill for documentation framework Create a Claude skill that helps agents write, review, and structure documentation using the Diataxis methodology. The skill uses a compressed index in SKILL.md paired with symlinked reference files from the framework repo, following the Vercel research pattern where passive context outperforms active retrieval. Includes the four documentation types (tutorials, how-to guides, reference, explanation) and the compass classification tool. Co-Authored-By: Claude Haiku 4.5 --- skills/diataxis/SKILL.md | 126 ++++++++++++++++++ skills/diataxis/references/application.rst | 1 + skills/diataxis/references/compass.rst | 1 + .../references/complex-hierarchies.rst | 1 + skills/diataxis/references/explanation.rst | 1 + skills/diataxis/references/foundations.rst | 1 + skills/diataxis/references/how-to-guides.rst | 1 + .../references/how-to-use-diataxis.rst | 1 + skills/diataxis/references/map.rst | 1 + skills/diataxis/references/quality.rst | 1 + .../references/reference-explanation.rst | 1 + skills/diataxis/references/reference.rst | 1 + skills/diataxis/references/start-here.rst | 1 + skills/diataxis/references/theory.rst | 1 + .../diataxis/references/tutorials-how-to.rst | 1 + skills/diataxis/references/tutorials.rst | 1 + 16 files changed, 141 insertions(+) create mode 100644 skills/diataxis/SKILL.md create mode 120000 skills/diataxis/references/application.rst create mode 120000 skills/diataxis/references/compass.rst create mode 120000 skills/diataxis/references/complex-hierarchies.rst create mode 120000 skills/diataxis/references/explanation.rst create mode 120000 skills/diataxis/references/foundations.rst create mode 120000 skills/diataxis/references/how-to-guides.rst create mode 120000 skills/diataxis/references/how-to-use-diataxis.rst create mode 120000 skills/diataxis/references/map.rst create mode 120000 skills/diataxis/references/quality.rst create mode 120000 skills/diataxis/references/reference-explanation.rst create mode 120000 skills/diataxis/references/reference.rst create mode 120000 skills/diataxis/references/start-here.rst create mode 120000 skills/diataxis/references/theory.rst create mode 120000 skills/diataxis/references/tutorials-how-to.rst create mode 120000 skills/diataxis/references/tutorials.rst diff --git a/skills/diataxis/SKILL.md b/skills/diataxis/SKILL.md new file mode 100644 index 0000000..e66b342 --- /dev/null +++ b/skills/diataxis/SKILL.md @@ -0,0 +1,126 @@ +--- +name: diataxis +description: > + Write, review, classify, and restructure documentation using the Diataxis framework. + Diataxis defines four documentation types — tutorials, how-to guides, reference, explanation — + based on two axes: action vs. cognition, and acquisition vs. application. + Use when writing docs, reviewing docs for quality, classifying existing content into the four types, + restructuring documentation, deciding what kind of doc to write, or when asked about + "Diataxis", "documentation types", "tutorial vs how-to", "reference vs explanation", + "documentation structure", "documentation quality", or "documentation framework". +--- + +# Diataxis Documentation Framework + +IMPORTANT: Prefer retrieval-led reasoning over pre-training-led reasoning for any documentation tasks. Always consult the reference files below rather than relying on general knowledge. + +## Source of Truth + +All reference files below are symlinked from the Diataxis repo and always reflect the latest content. Read them for authoritative guidance. + +## Compressed Index + +``` +references/ +├── Core +│ ├── start-here.rst — 5-min primer: the four types + two axes +│ ├── theory.rst — Full theoretical grounding +│ ├── foundations.rst — Why documentation needs structure +│ ├── map.rst — The two-dimensional map (action/cognition x acquisition/application) +│ └── compass.rst — Decision tool: classify content into the four types +├── The Four Types +│ ├── tutorials.rst — Principles for learning-oriented docs (lessons, guided practice) +│ ├── how-to-guides.rst — Principles for goal-oriented docs (step-by-step task completion) +│ ├── reference.rst — Principles for information-oriented docs (austere descriptions) +│ └── explanation.rst — Principles for understanding-oriented docs (context, why, discussion) +├── Key Distinctions +│ ├── tutorials-how-to.rst — Tutorial vs how-to: the most common confusion +│ └── reference-explanation.rst — Reference vs explanation: when to describe vs discuss +└── Applying Diataxis + ├── application.rst — Practical application guide + ├── how-to-use-diataxis.rst — Iterative workflow: assess → decide → act → repeat + ├── complex-hierarchies.rst — Handling large/complex doc structures + └── quality.rst — Functional quality vs deep quality +``` + +## The Four Types at a Glance + +``` + │ ACTION (practical) │ COGNITION (theoretical) +──────────────┼────────────────────────┼────────────────────────── + ACQUISITION │ TUTORIAL │ EXPLANATION + (study) │ "We will..." │ "The reason is..." + │ Learning experience │ Context, why, discussion +──────────────┼────────────────────────┼────────────────────────── + APPLICATION │ HOW-TO GUIDE │ REFERENCE + (work) │ "If you want x, do y" │ "X is / X does..." + │ Task completion │ Austere description +``` + +## Compass — Classify Any Content + +Ask two questions: +1. Does it inform **action** (do something) or **cognition** (understand something)? +2. Does it serve **acquisition** (learning/study) or **application** (working/doing)? + +Result: action+acquisition=tutorial | action+application=how-to | cognition+application=reference | cognition+acquisition=explanation + +For full decision logic, read `references/compass.rst`. + +## Quick Rules Per Type + +### Tutorials +- Provide a learning experience through doing, not teaching +- Show the goal upfront, deliver visible results early +- Use "We will..." language; minimize explanation (link to it) +- Must be perfectly reliable — learner must never get stuck +- Read `references/tutorials.rst` for full principles + +### How-to Guides +- Address real-world goals, not machinery operations +- Assume competence; focus purely on action +- Title = exactly what the guide shows how to do +- Handle edge cases; omit the unnecessary +- Read `references/how-to-guides.rst` for full principles + +### Reference +- Describe and only describe — neutral, austere, complete +- Mirror the structure of the thing being documented +- Adopt standard, consistent patterns throughout +- Provide examples for illustration, not explanation +- Read `references/reference.rst` for full principles + +### Explanation +- Make connections, provide context, explain why +- Admit opinion and perspective; consider alternatives +- Can discuss history, design decisions, trade-offs +- Keep closely bounded to the topic +- Read `references/explanation.rst` for full principles + +## Common Mistakes + +| Mistake | Fix | +|---|---| +| Tutorial explains too much | Move explanation to explanation docs, link to it | +| How-to teaches background | Strip to action steps only | +| Reference includes opinions | Move discussion to explanation | +| Explanation gives step-by-step | Move procedure to how-to guide | +| Mixing types in one doc | Split into separate docs by type | + +For the critical tutorial-vs-howto distinction, read `references/tutorials-how-to.rst`. +For reference-vs-explanation, read `references/reference-explanation.rst`. + +## Workflow for Applying Diataxis + +1. Pick any piece of documentation +2. Use the compass to classify it (action/cognition x acquisition/application) +3. Assess: does it serve the identified user need well? +4. Decide one single improvement action +5. Do it and ship it +6. Repeat + +Do not plan a grand restructuring. Work iteratively, one improvement at a time. Documentation is never finished but always complete. + +For full workflow guidance, read `references/how-to-use-diataxis.rst`. +For complex documentation structures, read `references/complex-hierarchies.rst`. +For quality theory (functional vs deep quality), read `references/quality.rst`. diff --git a/skills/diataxis/references/application.rst b/skills/diataxis/references/application.rst new file mode 120000 index 0000000..23d5278 --- /dev/null +++ b/skills/diataxis/references/application.rst @@ -0,0 +1 @@ +../../../application.rst \ No newline at end of file diff --git a/skills/diataxis/references/compass.rst b/skills/diataxis/references/compass.rst new file mode 120000 index 0000000..ab9ca38 --- /dev/null +++ b/skills/diataxis/references/compass.rst @@ -0,0 +1 @@ +../../../compass.rst \ No newline at end of file diff --git a/skills/diataxis/references/complex-hierarchies.rst b/skills/diataxis/references/complex-hierarchies.rst new file mode 120000 index 0000000..ec7cfd8 --- /dev/null +++ b/skills/diataxis/references/complex-hierarchies.rst @@ -0,0 +1 @@ +../../../complex-hierarchies.rst \ No newline at end of file diff --git a/skills/diataxis/references/explanation.rst b/skills/diataxis/references/explanation.rst new file mode 120000 index 0000000..4704e97 --- /dev/null +++ b/skills/diataxis/references/explanation.rst @@ -0,0 +1 @@ +../../../explanation.rst \ No newline at end of file diff --git a/skills/diataxis/references/foundations.rst b/skills/diataxis/references/foundations.rst new file mode 120000 index 0000000..ae45a3a --- /dev/null +++ b/skills/diataxis/references/foundations.rst @@ -0,0 +1 @@ +../../../foundations.rst \ No newline at end of file diff --git a/skills/diataxis/references/how-to-guides.rst b/skills/diataxis/references/how-to-guides.rst new file mode 120000 index 0000000..4f456e7 --- /dev/null +++ b/skills/diataxis/references/how-to-guides.rst @@ -0,0 +1 @@ +../../../how-to-guides.rst \ No newline at end of file diff --git a/skills/diataxis/references/how-to-use-diataxis.rst b/skills/diataxis/references/how-to-use-diataxis.rst new file mode 120000 index 0000000..61f78f9 --- /dev/null +++ b/skills/diataxis/references/how-to-use-diataxis.rst @@ -0,0 +1 @@ +../../../how-to-use-diataxis.rst \ No newline at end of file diff --git a/skills/diataxis/references/map.rst b/skills/diataxis/references/map.rst new file mode 120000 index 0000000..9d027ef --- /dev/null +++ b/skills/diataxis/references/map.rst @@ -0,0 +1 @@ +../../../map.rst \ No newline at end of file diff --git a/skills/diataxis/references/quality.rst b/skills/diataxis/references/quality.rst new file mode 120000 index 0000000..91420e8 --- /dev/null +++ b/skills/diataxis/references/quality.rst @@ -0,0 +1 @@ +../../../quality.rst \ No newline at end of file diff --git a/skills/diataxis/references/reference-explanation.rst b/skills/diataxis/references/reference-explanation.rst new file mode 120000 index 0000000..87739f6 --- /dev/null +++ b/skills/diataxis/references/reference-explanation.rst @@ -0,0 +1 @@ +../../../reference-explanation.rst \ No newline at end of file diff --git a/skills/diataxis/references/reference.rst b/skills/diataxis/references/reference.rst new file mode 120000 index 0000000..68a8fd0 --- /dev/null +++ b/skills/diataxis/references/reference.rst @@ -0,0 +1 @@ +../../../reference.rst \ No newline at end of file diff --git a/skills/diataxis/references/start-here.rst b/skills/diataxis/references/start-here.rst new file mode 120000 index 0000000..ffdcd81 --- /dev/null +++ b/skills/diataxis/references/start-here.rst @@ -0,0 +1 @@ +../../../start-here.rst \ No newline at end of file diff --git a/skills/diataxis/references/theory.rst b/skills/diataxis/references/theory.rst new file mode 120000 index 0000000..6cd5f3c --- /dev/null +++ b/skills/diataxis/references/theory.rst @@ -0,0 +1 @@ +../../../theory.rst \ No newline at end of file diff --git a/skills/diataxis/references/tutorials-how-to.rst b/skills/diataxis/references/tutorials-how-to.rst new file mode 120000 index 0000000..7d1eefb --- /dev/null +++ b/skills/diataxis/references/tutorials-how-to.rst @@ -0,0 +1 @@ +../../../tutorials-how-to.rst \ No newline at end of file diff --git a/skills/diataxis/references/tutorials.rst b/skills/diataxis/references/tutorials.rst new file mode 120000 index 0000000..c94fcce --- /dev/null +++ b/skills/diataxis/references/tutorials.rst @@ -0,0 +1 @@ +../../../tutorials.rst \ No newline at end of file