diataxis
Four-quadrant documentation framework. Produces tutorials (learning by doing), how-to guides (goal-oriented tasks), reference documentation (authoritative description), and explanation (conceptual understanding) using the Diataxis methodology. Invoke when creating new documentation, auditing existing docs for quadrant mixing, or classifying documentation requests. Triggers: documentation, tutorial, how-to, howto, reference docs, explanation, diataxis, write docs, write documentation, write tutorial, create documentation, classify documentation, audit documentation, user guide, getting started, quickstart, API docs, developer guide, quadrant, doc type, how-to guide.
Best use case
diataxis is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Four-quadrant documentation framework. Produces tutorials (learning by doing), how-to guides (goal-oriented tasks), reference documentation (authoritative description), and explanation (conceptual understanding) using the Diataxis methodology. Invoke when creating new documentation, auditing existing docs for quadrant mixing, or classifying documentation requests. Triggers: documentation, tutorial, how-to, howto, reference docs, explanation, diataxis, write docs, write documentation, write tutorial, create documentation, classify documentation, audit documentation, user guide, getting started, quickstart, API docs, developer guide, quadrant, doc type, how-to guide.
Teams using diataxis should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/diataxis/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How diataxis Compares
| Feature / Agent | diataxis | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Four-quadrant documentation framework. Produces tutorials (learning by doing), how-to guides (goal-oriented tasks), reference documentation (authoritative description), and explanation (conceptual understanding) using the Diataxis methodology. Invoke when creating new documentation, auditing existing docs for quadrant mixing, or classifying documentation requests. Triggers: documentation, tutorial, how-to, howto, reference docs, explanation, diataxis, write docs, write documentation, write tutorial, create documentation, classify documentation, audit documentation, user guide, getting started, quickstart, API docs, developer guide, quadrant, doc type, how-to guide.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Diataxis Skill
> **Version:** 0.1.0
> **Framework:** Diataxis Four-Quadrant Documentation (diataxis.fr)
> **Constitutional Compliance:** Jerry Constitution v1.0
> **Knowledge Reference:** `docs/knowledge/diataxis-framework.md`
## Document Sections
| Section | Purpose |
|---------|---------|
| [Purpose](#purpose) | What the skill does and key capabilities |
| [When to Use This Skill](#when-to-use-this-skill) | Activation conditions and exclusions |
| [Available Agents](#available-agents) | Agent roster with roles, tiers, and output locations |
| [P-003 Compliance](#p-003-compliance) | Single-level nesting hierarchy and architectural rationale |
| [Invoking an Agent](#invoking-an-agent) | Three invocation patterns with examples |
| [Templates](#templates) | Per-quadrant template references |
| [Integration Points](#integration-points) | Cross-skill connections |
| [Constitutional Compliance](#constitutional-compliance) | Principle mapping |
| [Quick Reference](#quick-reference) | Common workflows table |
| [References](#references) | All referenced file paths |
This SKILL.md serves multiple audiences:
## Document Audience (Triple-Lens)
| Level | Audience | Sections to Focus On |
|-------|----------|---------------------|
| **L0 (ELI5)** | New users, stakeholders | [Purpose](#purpose), [When to Use](#when-to-use-this-skill), [Quick Reference](#quick-reference) |
| **L1 (Engineer)** | Developers invoking agents | [Invoking an Agent](#invoking-an-agent), [Available Agents](#available-agents), [Templates](#templates) |
| **L2 (Architect)** | Workflow designers | [P-003 Compliance](#p-003-compliance), [Integration Points](#integration-points), [Constitutional Compliance](#constitutional-compliance) |
---
## Purpose
The Diataxis skill provides **four-quadrant documentation methodology** using the Diataxis framework (diataxis.fr). Instead of writing documentation as a single undifferentiated blob, this skill separates content into four types based on two axes: practical/theoretical and acquisition/application.
### Key Capabilities
- **Quadrant-Specific Writing** -- Four specialized writer agents, each encoding the quality criteria, anti-patterns, and voice for their quadrant
- **Documentation Classification** -- T1 classifier analyzes requests against the two Diataxis axes and returns structured quadrant assignment
- **Documentation Auditing** -- T2 auditor detects quadrant mixing, coverage gaps, and quality issues in existing documentation
- **Template-Driven Output** -- Per-quadrant templates enforce structural consistency
- **Self-Review Integration** -- Writer agents apply Diataxis-specific quality checks during H-15 self-review
### The Four Quadrants
| | **Acquisition** (learning) | **Application** (working) |
|--|:--:|:--:|
| **Practical** (doing) | Tutorials | How-to Guides |
| **Theoretical** (understanding) | Explanation | Reference |
---
## When to Use This Skill
Activate when:
- Writing new documentation for any project or skill
- Converting existing documentation to follow Diataxis quadrant structure
- Classifying whether a documentation request should be a tutorial, guide, reference, or explanation
- Auditing existing docs for quadrant mixing (the #1 documentation anti-pattern)
- Producing per-quadrant templates for consistent documentation structure
**Do NOT use when:**
- Writing code, tests, or non-documentation artifacts (use `/eng-team`)
- Performing adversarial quality review of non-documentation deliverables (use `/adversary`)
- Writing requirements specifications (use `/nasa-se`)
- The user explicitly requests free-form writing without Diataxis structure -- respect user preference per P-020
### Misclassification Recovery
If a writer agent produces the wrong document type:
1. If you know the correct type: invoke the correct writer agent directly
2. If unsure: invoke `diataxis-classifier` with a `hint_quadrant` parameter to confirm. The classifier returns a confidence level (1.00/0.85/0.70); for confidence below 0.85, use the `hint_quadrant` parameter to guide classification before proceeding.
---
## Available Agents
| Agent | Role | Cognitive Mode | Model | Tier | Output Location |
|-------|------|---------------|-------|------|----------------|
| `diataxis-tutorial` | Tutorial Writer (learning-oriented) | systematic | sonnet | T2 | `projects/${JERRY_PROJECT}/docs/tutorials/` |
| `diataxis-howto` | How-to Guide Writer (goal-oriented) | systematic | sonnet | T2 | `projects/${JERRY_PROJECT}/docs/how-to/` |
| `diataxis-reference` | Reference Writer (information-oriented) | systematic | sonnet | T2 | `projects/${JERRY_PROJECT}/docs/reference/` |
| `diataxis-explanation` | Explanation Writer (understanding-oriented) | divergent | opus | T2 | `projects/${JERRY_PROJECT}/docs/explanation/` |
| `diataxis-classifier` | Documentation Classifier | convergent | haiku | T1 | Inline result (no file output) |
| `diataxis-auditor` | Documentation Auditor | systematic | sonnet | T1 | Inline result; orchestrator persists to `projects/${JERRY_PROJECT}/audits/` |
---
## P-003 Compliance
All six agents are **workers** (invoked via Task by the caller). None include `Task` in their tools. The caller (user or orchestrator) is responsible for:
1. Invoking `diataxis-classifier` to determine the correct quadrant (optional when quadrant is unambiguous from the request)
2. Invoking the appropriate writer agent based on classification
3. Invoking `diataxis-auditor` for quality review
This design maintains P-003 single-level nesting: orchestrator -> worker only.
### Architectural Rationale
Four specialized writer agents (rather than one adaptive writer) is justified by cognitive mode differentiation: tutorial writing requires **systematic** step-by-step completeness, how-to writing requires **systematic** goal-oriented focus, reference writing requires **systematic** exhaustive coverage, and explanation writing requires **divergent** conceptual exploration. These are distinct reasoning patterns that produce measurably different output when encoded in agent identity rather than deferred to prompt-level switching. The classifier separates routing from writing; the auditor separates evaluation from production.
---
## Invoking an Agent
### Option 1: Natural Language Request
```
Write a tutorial for setting up Jerry's problem-solving skill.
```
The trigger map routes "write tutorial" to `/diataxis`, and the main context invokes `diataxis-tutorial`.
### Option 2: Explicit Agent Request
```
Use /diataxis with diataxis-classifier to classify this documentation request:
"How do I configure MCP servers in Jerry?"
Then use the appropriate writer agent based on the classification.
```
### Option 3: Task Tool Invocation (Programmatic)
Agent definitions in `skills/diataxis/agents/` follow the standard Jerry dual-file architecture (H-34). The orchestrator invokes them via the Task tool using the `jerry:diataxis-{agent}` subagent_type convention, which maps to the agent definition file at `skills/diataxis/agents/diataxis-{agent}.md`:
```
Task tool invocation:
subagent_type: "jerry:diataxis-tutorial"
prompt: "Write a tutorial for setting up your first Jerry project.
Topic: Setting up your first Jerry project
Prerequisites: Jerry installed, Claude Code configured
Output: projects/PROJ-013-diataxis/samples/tutorial-first-project.md"
```
The same pattern applies to all six agents: `jerry:diataxis-classifier`, `jerry:diataxis-tutorial`, `jerry:diataxis-howto`, `jerry:diataxis-reference`, `jerry:diataxis-explanation`, `jerry:diataxis-auditor`. (Note: verify `jerry:` namespace support against your Claude Code version before programmatic deployment.)
---
## Templates
Per-quadrant templates are located at `skills/diataxis/templates/`:
| Template | Quadrant | Key Structural Elements |
|----------|----------|------------------------|
| `skills/diataxis/templates/tutorial-template.md` | Tutorial | Numbered steps; prerequisite block; "What you will achieve" intro; observable output per step |
| `skills/diataxis/templates/howto-template.md` | How-to Guide | Goal statement title; numbered task steps; "If you need X, do Y" variants |
| `skills/diataxis/templates/reference-template.md` | Reference | Table/definition-list structure; no narrative; standard entry format |
| `skills/diataxis/templates/explanation-template.md` | Explanation | Continuous prose sections; no numbered steps; "Why" framing |
---
## Integration Points
- **`/problem-solving`**: Research outputs may need documentation -- classifier determines which quadrant
- **`/nasa-se`**: Requirements and design artifacts feed reference documentation
- **`/adversary`**: Diataxis agents integrate with creator-critic-revision cycle (H-14) for C2+ deliverables
- **`/eng-team`**: Security documentation benefits from quadrant separation
- **Jerry's own docs**: The skill can improve Jerry's own documentation (reflexive use)
### Documentation Quality Gate
For C2+ documentation deliverables:
1. Writer agent produces document
2. `diataxis-auditor` reviews for quadrant mixing and quality criteria
3. S-014 scoring applied to final output via `/adversary` (adv-scorer agent) with 6-dimension weighted composite
---
## Constitutional Compliance
All agents comply with:
- **P-003** -- No recursive subagents. Workers cannot spawn sub-workers.
- **P-020** -- User authority. User can override quadrant classification. If a user explicitly requests a different quadrant or rejects a classification, the agent complies without requiring justification.
- **P-022** -- No deception. Agents are transparent about classification confidence and limitations.
---
## Quick Reference
| Need | Agent | Example | Output Location |
|------|-------|---------| ------|
| Write a tutorial | `diataxis-tutorial` | "Write a tutorial for setting up X" | `projects/${JERRY_PROJECT}/docs/tutorials/` |
| Write a how-to guide | `diataxis-howto` | "Write a how-to guide for deploying Y" | `projects/${JERRY_PROJECT}/docs/how-to/` |
| Write reference docs | `diataxis-reference` | "Document the API for Z" | `projects/${JERRY_PROJECT}/docs/reference/` |
| Write an explanation | `diataxis-explanation` | "Explain why we chose architecture A" | `projects/${JERRY_PROJECT}/docs/explanation/` |
| Classify a doc request | `diataxis-classifier` | "What type of doc should 'Getting Started' be?" | Inline result (no file output) |
| Audit existing docs | `diataxis-auditor` | "Audit these files for quadrant mixing" | `projects/${JERRY_PROJECT}/audits/` |
---
## References
| Source | Content |
|--------|---------|
| `docs/knowledge/diataxis-framework.md` | Diataxis framework knowledge base |
| `skills/diataxis/rules/diataxis-standards.md` | Per-quadrant quality criteria, anti-patterns, detection heuristics, voice guidelines |
| `skills/diataxis/agents/diataxis-tutorial.md` | Tutorial writer agent definition |
| `skills/diataxis/agents/diataxis-howto.md` | How-to guide writer agent definition |
| `skills/diataxis/agents/diataxis-reference.md` | Reference writer agent definition |
| `skills/diataxis/agents/diataxis-explanation.md` | Explanation writer agent definition |
| `skills/diataxis/agents/diataxis-classifier.md` | Documentation classifier agent definition |
| `skills/diataxis/agents/diataxis-auditor.md` | Documentation auditor agent definition |
| `skills/diataxis/templates/tutorial-template.md` | Tutorial structural template |
| `skills/diataxis/templates/howto-template.md` | How-to guide structural template |
| `skills/diataxis/templates/reference-template.md` | Reference structural template |
| `skills/diataxis/templates/explanation-template.md` | Explanation structural template |
---
*Skill Version: 0.1.0*
*Constitutional Compliance: Jerry Constitution v1.0*
*SSOT: `.context/rules/skill-standards.md`*
*Created: 2026-02-26*Related Skills
ux-lean-ux
Lean UX hypothesis-driven design sub-skill for the /user-experience parent skill. Facilitates Build-Measure-Learn cycles using Jeff Gothelf and Josh Seiden's Lean UX methodology (3rd ed. 2021). Produces hypothesis backlogs, assumption maps, MVP experiment designs, and validated learning logs. Invoke when teams need hypothesis-driven iteration, assumption mapping, experiment design, or validated learning documentation. Invoked by ux-orchestrator during Wave 2 lifecycle-stage routing or when user intent is "testing hypotheses" during the "During design" stage. Triggers: lean UX, hypothesis, assumption mapping, build-measure-learn, MVP experiment, validated learning, experiment design, hypothesis backlog.
ux-kano-model
Kano model feature classification and prioritization sub-skill for the /user-experience parent skill. Classifies product features into Must-be (M), Performance (O), Attractive (A), Indifferent (I), and Reverse (R) categories using the functional/dysfunctional questionnaire pair methodology (Kano et al., 1984). Computes Customer Satisfaction (CS) coefficients (Better/Worse) for priority matrix visualization. Produces feature classification reports, priority matrices, and survey design templates. Sample size awareness: 5-8 respondents yields directional classification only (MEDIUM confidence); 20+ respondents required for statistical classification (Berger et al., 1993). Invoked by ux-orchestrator during Wave 4 lifecycle-stage routing or when user intent is "Need to prioritize features" at any lifecycle stage. Triggers: Kano, must-be, attractive, one-dimensional, performance feature, satisfaction, feature classification, delighter, feature prioritization, CS coefficient.
ux-jtbd
Jobs-to-Be-Done research and analysis sub-skill for the /user-experience parent skill. Conducts JTBD job statement synthesis, switch interview analysis (Moesta/Spiek four forces), outcome-driven innovation (Ulwick ODI), and job mapping for tiny teams (1-5 people). Invoked by ux-orchestrator when users need to understand user motivations, map jobs to be done, identify switch triggers, or produce job maps with outcome expectations. Sub-skill of /user-experience; routed via ux-orchestrator lifecycle-stage triage. Triggers: JTBD, jobs to be done, switch interview, job mapping, user motivation, outcome, hiring criteria, user jobs, switch forces.
ux-inclusive-design
Inclusive design and WCAG 2.2 accessibility evaluation sub-skill for the /user-experience parent skill. Performs WCAG 2.2 compliance audits across Perceivable, Operable, Understandable, and Robust principles (conformance levels A, AA, AAA) and applies Microsoft Inclusive Design methodology including Persona Spectrum analysis (permanent, temporary, situational disabilities). Produces accessibility audit reports and persona spectrum analyses. Invoke when teams need accessibility compliance evaluation, WCAG conformance auditing, screen reader compatibility assessment, color contrast analysis, cognitive load evaluation, or inclusive design review. Invoked by ux-orchestrator during Wave 3 lifecycle-stage routing or when user intent is "Check accessibility" at any lifecycle stage. Triggers: accessibility, WCAG, ARIA, screen reader, contrast, cognitive load, inclusive, a11y, inclusive design, WCAG 2.2, persona spectrum.
ux-heuristic-eval
Nielsen heuristic evaluation sub-skill for the /user-experience parent skill. Evaluates interfaces against Nielsen's 10 usability heuristics, produces severity-rated findings on a 0-4 scale (Cosmetic to Catastrophic), and generates remediation recommendations with effort estimates. Invoke when teams need structured usability evaluation, interface review, heuristic audit, or severity-rated UX findings. Invoked by ux-orchestrator during Wave 1 lifecycle-stage routing or CRISIS mode triage. Triggers: heuristic evaluation, usability audit, Nielsen heuristics, interface review, severity rating, usability inspection, UX evaluation.
ux-heart-metrics
HEART Metrics framework sub-skill for the /user-experience parent skill. Applies Google's HEART framework (Happiness, Engagement, Adoption, Retention, Task Success) using the Goals-Signals-Metrics (GSM) process to define measurable UX metrics for products and features. Invoked by ux-orchestrator when users need to measure UX health, define UX metrics, establish measurement baselines, or produce dashboard-ready metric specifications. Sub-skill of /user-experience; routed via ux-orchestrator lifecycle-stage triage. Triggers: HEART, metrics, happiness, engagement, adoption, retention, task success, GSM, measurement, UX metrics, dashboard, goals signals metrics.
ux-design-sprint
AJ&Smart Design Sprint 2.0 facilitation sub-skill for the /user-experience parent skill. Facilitates a structured four-day rapid prototyping and validation process compressed from the Google Ventures five-day Design Sprint (Knapp, Zeratsky & Kowitz, 2016; Courtney, 2019). Produces sprint artifacts including challenge maps, solution sketches, storyboards, realistic prototypes, and structured user interview findings with synthesis confidence gates. Invoke when teams need to rapidly validate a product concept, solve a critical design challenge through structured prototyping, test ideas with real users before committing to development, or explore solution directions when they do not know what to build. Triggers: design sprint, GV sprint, rapid prototyping, sprint week, map sketch decide test, 4-day sprint, design sprint 2.0, AJ Smart sprint, validate prototype, test with users, sprint facilitation.
ux-behavior-design
Fogg Behavior Model B=MAP bottleneck diagnosis sub-skill for the /user-experience parent skill. Diagnoses why users fail to take desired actions by analyzing the three B=MAP factors (Motivation, Ability, Prompt) and identifying which factor falls below the action threshold. Produces bottleneck diagnoses, factor-level assessments, and intervention recommendations with synthesis confidence gates. Invoke when teams need to understand why users are not completing a specific action, diagnose behavioral bottlenecks, design behavior change interventions, or analyze post-launch user inaction patterns. Invoked by ux-orchestrator during Wave 4 lifecycle-stage routing or when user intent is "Users not completing action" during the "After launch" stage. Triggers: behavior design, B=MAP, Fogg model, behavior bottleneck, motivation analysis, ability analysis, prompt design, why users don't, user inaction, behavior diagnosis, tiny habits, action threshold.
ux-atomic-design
Atomic Design component taxonomy sub-skill for the /user-experience parent skill. Implements Brad Frost's 5-level component hierarchy (Atoms, Molecules, Organisms, Templates, Pages) for design system architecture. Produces component inventories, design token audits, composition rules, and Storybook coverage reports. Invoke when teams need component taxonomy construction, design system architecture, Storybook integration, design token consistency analysis, or component reuse auditing. Invoked by ux-orchestrator during Wave 3 lifecycle-stage routing or when user intent is "Building component system" during the "During design" stage. Triggers: atomic design, component taxonomy, design tokens, Storybook, atoms molecules organisms, design system, component inventory, component library.
ux-ai-first-design
AI-first interaction design sub-skill (CONDITIONAL) for the /user-experience parent skill. Provides trust-calibrated AI interaction design guidance using Yang et al.'s trust-risk and error-risk classification framework. Produces interaction pattern recommendations, trust calibration assessments, feedback loop designs, and progressive disclosure strategies for AI-powered features. CONDITIONAL: requires WSM >= 7.80 AND enabler research (FEAT-020) complete; otherwise routes to /ux-heuristic-eval with PAIR protocol. Invoke when teams need to design AI-powered interactions, calibrate user trust in AI outputs, classify AI error risks, design human-AI handoff patterns, or audit existing AI interfaces for trust and safety. Triggers: AI-first design, AI interaction, trust calibration, AI UX, conversational UX, AI interface, LLM interface, agentic UX, human-AI interaction, AI transparency, AI error handling, AI onboarding, progressive AI disclosure, trust-risk, error-risk.
user-experience
Parent orchestrator for AI-augmented UX methodology targeting tiny teams (1-5 people). Routes to 10 sub-skills by product lifecycle stage through criteria-gated waves. Invoke when team needs structured UX evaluation, user research, design systems, UX metrics, behavior diagnosis, feature prioritization, design sprints, or AI interaction design. Each sub-skill implements a proven UX framework with synthesis hypothesis confidence gates and MCP design tool integration. Triggers: UX, user experience, usability, heuristic evaluation, JTBD, lean UX, HEART metrics, atomic design, inclusive design, behavior design, Kano model, design sprint, AI-first design, UX audit, accessibility, design system, user research.
use-case
Guided use case authoring and decomposition using Cockburn's 12-step writing process and Jacobson UC 2.0 progressive narrative levels. Creates structured use case artifacts with YAML frontmatter validated against use-case-realization-v1.schema.json. Decomposes use cases into implementation-ready slices with INVEST criteria verification and produces realization interaction sequences for downstream /test-spec and /contract-design consumption. Invoke when writing, creating, authoring, elaborating, slicing, decomposing, or realizing use cases.