ReddRadar
Agent skill
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.
Install this agent skill to your Project
npx add-skill https://github.com/joaquimscosta/arkhe-claude-plugins/tree/main/plugins/doc/skills/diataxis
SKILL.md
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
Recommended Agent Skills
Expand your agent's capabilities with these related and highly-rated skills.
joaquimscosta/arkhe-claude-plugins
Skill Name
What this skill does. Use when user mentions "keyword1", "keyword2", or "keyword3". Keep under 1,024 characters and include specific trigger keywords.
joaquimscosta/arkhe-claude-plugins
plugin-release-checker
joaquimscosta/arkhe-claude-plugins
skill-validator
Validate skills against Anthropic best practices for frontmatter, structure, content, file organization, hooks, MCP, and security (62 rules in 8 categories). Use when creating new skills, updating existing skills, before publishing skills, reviewing skill quality, or when user mentions "validate skill", "check skill", "skill best practices", "skill review", or "lint skill".
joaquimscosta/arkhe-claude-plugins
sync-docs
Sync official Anthropic documentation and analyze impact on project components. Runs docs/reference/update-claude-docs.sh, computes diffs, and reports impacts on the skill validator, plugins, and project documentation. Use when user mentions "sync docs", "update reference docs", "refresh docs", or "check doc changes".
joaquimscosta/arkhe-claude-plugins
research-frontmatter
Enforce standard YAML frontmatter on research documents in docs/research/. Use when creating, editing, or promoting research files, when user mentions "research metadata", "research frontmatter", or "research staleness".
joaquimscosta/arkhe-claude-plugins
deep-research
Deep research on technical topics using EXA tools with intelligent two-tier caching. Use when user asks to research a topic, investigate best practices, look up information, find patterns, or explore architectures. Also invoked by /research command. Triggers: "research", "look up", "investigate", "deep dive", "find information about", "what are best practices for", "how do others implement".
Didn't find tool you were looking for?