Diátaxis Agent Skill

This skill treats documentation as a governed system: Diátaxis provides the taxonomy, this skill enforces intent, and AI operates only within explicit bounds.

An agent skill that enables AI agents to classify, validate, generate, and audit documentation using the Diátaxis framework. Enforces quadrant purity across tutorials, how-to guides, reference, and explanation.

What This Skill Does

• Classify documentation into one of four Diátaxis quadrants
• Audit documentation sets for gaps, imbalances, and violations
• Generate new documentation with strict quadrant adherence
• Restructure mixed-mode documents into pure quadrant documents

The skill enforces single-quadrant purity: one document serves one purpose. When quadrant purity cannot be maintained, refusal with explanation is a valid outcome.

The Four Quadrants

Installation

Option 1: Copy to Your Skills Directory

Clone this repository and copy the diataxis/ folder to your agent’s skills directory:

Cursor

# Project-level
cp -r diataxis/ .cursor/skills/diataxis/

# User-level (global)
cp -r diataxis/ ~/.cursor/skills/diataxis/

Claude Code

# Project-level
cp -r diataxis/ .claude/skills/diataxis/

# User-level (global)
cp -r diataxis/ ~/.claude/skills/diataxis/

Codex

# Project-level
cp -r diataxis/ .codex/skills/diataxis/

# User-level (global)
cp -r diataxis/ ~/.codex/skills/diataxis/

Option 2: Install via skills.sh

npx skills add keithpatton/diataxis-agent-skill

Usage

Once installed, the skill activates when you:

• Ask to create, review, or audit documentation
• Mention Diátaxis, documentation structure, or doc quality
• Request help with tutorials, how-to guides, reference docs, or explanations

Example Prompts

Classification:

“Classify this documentation and tell me which Diátaxis quadrant it belongs to.”

Audit:

“Audit the docs/ folder for Diátaxis compliance and report any violations.”

Generation:

“Write a how-to guide for configuring SSL certificates.”

Restructure:

“This README mixes tutorial and reference content. Split it into separate documents.”

Skill Structure

diataxis/
├── SKILL.md                    # Main skill file (the "constitution")
└── references/
    ├── quadrants.md            # Detailed quadrant characteristics
    ├── compass.md              # Classification decision tree
    └── anti-patterns.md        # Violation detection and fixes

Key Behaviors

Classification Output

All classifications include confidence and evidence:

Classified as How-to (high confidence).
Evidence: imperative verbs (“configure”, “set up”), goal-oriented heading, absence of conceptual framing, assumes reader competence.

Generate Mode Policy

For generation, one of the following must be true:

• You explicitly state the target quadrant (“write a How-to for X”), OR
• The agent classifies the request, presents reasoning, and receives your confirmation

Refusal as Success

When quadrant purity cannot be maintained, refusal with explanation is a valid and successful outcome. The skill will recommend splitting content rather than blending quadrants.

Attribution

Diátaxis is the work of Daniele Procida.

This skill encodes the Diátaxis framework for use by AI agents. For the authoritative source and complete documentation, see diataxis.fr.

The Diátaxis framework is licensed under CC-BY-SA 4.0. Citation metadata is available at the Diátaxis GitHub repository.

License

This skill is licensed under CC-BY-SA 4.0 (Creative Commons Attribution-ShareAlike 4.0 International), in compliance with the Diátaxis framework’s ShareAlike requirement.

You are free to:

• Share — copy and redistribute the material in any medium or format
• Adapt — remix, transform, and build upon the material for any purpose

Under the following terms:

• Attribution — You must give appropriate credit to both this skill and the original Diátaxis framework
• ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license

Contributing

Contributions are welcome. Please ensure any changes maintain alignment with the Diátaxis framework as documented by Daniele Procida.

See Also

• Diátaxis — The authoritative source
• Agent Skills — The skills ecosystem
• Cursor Skills Documentation