Classify, validate, generate, and audit documentation using the Diátaxis framework. Enforces quadrant purity across tutorials, how-to guides, reference, and explanation. Use when creating documentation, reviewing docs, auditing doc sets, restructuring existing content, or when the user mentions Diátaxis, documentation structure, or doc quality.
86
78%
Does it follow best practices?
Impact
98%
1.08xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./diataxis/SKILL.mdQuality
Discovery
100%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is an excellent skill description that hits all the marks. It provides specific concrete actions, includes a comprehensive 'Use when...' clause with natural trigger terms, and occupies a clearly distinct niche through the Diátaxis framework focus. The description is concise yet thorough, using proper third-person voice throughout.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple specific concrete actions: classify, validate, generate, audit documentation. Also specifies the framework (Diátaxis) and mentions quadrant purity across four specific document types (tutorials, how-to guides, reference, explanation). | 3 / 3 |
Completeness | Clearly answers both 'what' (classify, validate, generate, audit documentation using Diátaxis; enforce quadrant purity) and 'when' with an explicit 'Use when...' clause listing multiple trigger scenarios (creating docs, reviewing docs, auditing doc sets, restructuring content, mentioning Diátaxis/documentation structure/doc quality). | 3 / 3 |
Trigger Term Quality | Includes strong natural keywords users would say: 'documentation', 'docs', 'Diátaxis', 'documentation structure', 'doc quality', 'tutorials', 'how-to guides', 'reference', 'explanation', 'reviewing docs', 'auditing doc sets', 'restructuring existing content'. Good coverage of natural variations. | 3 / 3 |
Distinctiveness Conflict Risk | The Diátaxis framework is a very specific niche that clearly distinguishes this from generic documentation or writing skills. The mention of 'quadrant purity', specific quadrant types, and the framework name make it highly unlikely to conflict with other skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
57%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is a well-organized skill that clearly defines the Diátaxis framework and its operating modes, with good progressive disclosure to reference files. Its main weaknesses are moderate verbosity in quadrant descriptions that Claude likely already understands, and a lack of concrete output templates/examples for each operating mode beyond classification. The workflows would benefit from explicit validation steps and feedback loops, particularly for audit and restructure modes.
Suggestions
Add concrete output templates for audit and restructure modes (e.g., a sample audit report table, a restructure proposal format) to match the classification example already provided.
Tighten the quadrant summaries—Claude knows Diátaxis well enough that the 'Not' lists and language examples could be condensed into a single reference table or moved to references/quadrants.md.
Add explicit validation/feedback loops to the audit and restructure workflows (e.g., 'After classifying each document, cross-check against the compass table; if confidence is low, flag for human review before proceeding').
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is reasonably well-structured but includes some content Claude likely already knows about Diátaxis (the full quadrant descriptions are somewhat verbose). The compass table and quadrant summaries are useful reference material, but the 'Not' lists and some language examples could be tighter. The attribution section, while appropriate, adds tokens that don't help Claude execute the skill. | 2 / 3 |
Actionability | The skill provides clear operating modes and workflows with specific steps, and the output requirements section gives a concrete example of classification output. However, it lacks executable examples for generation, audit reports, or restructure plans—these are described abstractly rather than with concrete templates or copy-paste-ready formats. | 2 / 3 |
Workflow Clarity | Each operating mode has a numbered workflow, and the generate mode includes a validation gate (confirm quadrant before producing content). However, the workflows lack explicit validation checkpoints and feedback loops—for example, the audit workflow doesn't specify what to do when violations are found beyond 'report imbalances,' and the restructure workflow's 'present plan for user confirmation' is the only checkpoint across all modes. | 2 / 3 |
Progressive Disclosure | The skill effectively uses progressive disclosure with a clear overview in the main file and well-signaled one-level-deep references to detailed materials (references/quadrants.md, references/compass.md, references/anti-patterns.md). The Additional Resources section provides clear navigation to supplementary content. | 3 / 3 |
Total | 9 / 12 Passed |
Validation
100%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
5b095a5
Table of Contents
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.