Skill

diataxis

Generates Diataxis four-quadrant docs: tutorials (learn-by-doing), how-to guides (tasks), references (facts), explanations (concepts). For creating, auditing, classifying documentation.

Markdown

documentation

Install

npx claudepluginhub geekatron/jerry --plugin jerry

Tool Access

This skill is limited to using the following tools:

ReadWriteEditGlobGrepBash

Preview

> **Version:** 0.1.0

Supporting Assets

agents/diataxis-auditor.governance.yamlagents/diataxis-auditor.mdagents/diataxis-classifier.governance.yamlagents/diataxis-classifier.mdagents/diataxis-explanation.governance.yamlagents/diataxis-explanation.mdagents/diataxis-howto.governance.yamlagents/diataxis-howto.mdagents/diataxis-reference.governance.yamlagents/diataxis-reference.mdagents/diataxis-tutorial.governance.yamlagents/diataxis-tutorial.mdrules/diataxis-standards.mdtemplates/explanation-template.mdtemplates/howto-template.mdtemplates/reference-template.mdtemplates/tutorial-template.md

SKILL.md

Similar Skills

using-git-worktrees

Creates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.

superpowers

169.2k

subagent-driven-development

3 files

Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.

superpowers

169.2k

dispatching-parallel-agents

Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.

superpowers

169.2k

Stats

Stars19

Forks3

Last CommitApr 1, 2026

Actions

View Source View Plugin View on GitHub View README

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	What the skill does and key capabilities
When to Use This Skill	Activation conditions and exclusions
Available Agents	Agent roster with roles, tiers, and output locations
P-003 Compliance	Single-level nesting hierarchy and architectural rationale
Invoking an Agent	Three invocation patterns with examples
Templates	Per-quadrant template references
Integration Points	Cross-skill connections
Constitutional Compliance	Principle mapping
Quick Reference	Common workflows table
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, When to Use, Quick Reference
L1 (Engineer)	Developers invoking agents	Invoking an Agent, Available Agents, Templates
L2 (Architect)	Workflow designers	P-003 Compliance, Integration Points, 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:

If you know the correct type: invoke the correct writer agent directly
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:

Invoking diataxis-classifier to determine the correct quadrant (optional when quadrant is unambiguous from the request)
Invoking the appropriate writer agent based on classification
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:

Writer agent produces document
diataxis-auditor reviews for quadrant mixing and quality criteria
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