Structure, classify, and write documentation using the Diátaxis framework. Use when writing docs, README files, guides, tutorials, how-to guides, API references, or organizing documentation architecture. Also use when asked to improve documentation, restructure docs, decide what type of doc to write, or classify existing content. Covers tutorials, how-to guides, reference, and explanation.
99
100%
Does it follow best practices?
Impact
97%
1.10xAverage score across 3 eval scenarios
Passed
No known issues
Quality
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 a strong skill description that clearly communicates its purpose, scope, and trigger conditions. It names the specific framework (Diátaxis), lists concrete actions, provides comprehensive trigger terms covering multiple user phrasings, and has a clear niche that distinguishes it from generic documentation or writing skills. The description is well-structured and uses appropriate third-person voice throughout.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Lists multiple concrete actions: 'structure', 'classify', 'write documentation', 'improve documentation', 'restructure docs', 'decide what type of doc to write', 'classify existing content'. These are specific, actionable verbs tied to a clear domain. | 3 / 3 |
Completeness | Clearly answers both 'what' (structure, classify, and write documentation using the Diátaxis framework) and 'when' with explicit 'Use when...' clauses covering multiple trigger scenarios including writing, improving, restructuring, and classifying documentation. | 3 / 3 |
Trigger Term Quality | Excellent coverage of natural terms users would say: 'docs', 'README files', 'guides', 'tutorials', 'how-to guides', 'API references', 'documentation architecture', 'restructure docs', 'Diátaxis'. These cover many variations a user might naturally use when requesting documentation help. | 3 / 3 |
Distinctiveness Conflict Risk | The Diátaxis framework is a specific, well-defined niche that distinguishes this from generic writing or documentation skills. The mention of the four Diátaxis categories (tutorials, how-to guides, reference, explanation) and the framework name itself create clear, distinct triggers unlikely to conflict with general writing skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
100%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This is an exceptionally well-structured skill that efficiently teaches the Diátaxis framework. It provides a clear mental model (the 2×2 matrix), actionable principles for each documentation type, a concrete workflow with a worked example, and a comprehensive common mistakes table. The progressive disclosure is well-designed with clear pointers to 12 reference files for deeper guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is lean and efficient. It doesn't explain what documentation is or why it matters — it jumps straight into the framework's structure. Every section earns its place: the matrix, bullet points, compass, workflow, example, and common mistakes table are all dense with actionable information. No padding or unnecessary context. | 3 / 3 |
Actionability | The skill provides concrete, specific guidance: a classification matrix, bullet-pointed principles for each type, a step-by-step application workflow, a worked example showing the classification process in action, and a common mistakes table with specific fixes. While there's no code (appropriate for an instruction-only skill), every piece of guidance is specific and directly applicable. | 3 / 3 |
Workflow Clarity | The 'How To Apply' section provides a clear 5-step sequence: classify → check for mixing → separate → apply principles → link between types. The compass provides a decision framework (two questions → intersection). The worked example demonstrates the full workflow. For a non-destructive documentation task, this level of workflow clarity is excellent — no validation gaps exist for this domain. | 3 / 3 |
Progressive Disclosure | Excellent progressive disclosure structure. The main file provides a concise overview with key principles for each type, then clearly signals 12 reference files for deep dives in a well-organized table. References are one level deep and clearly named. The repeated pattern of 'Load references/X.md for full guidance' is consistent and easy to follow. However, no bundle files were provided to verify the references exist — scoring based on the structure as designed. | 3 / 3 |
Total | 12 / 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.
40067f1
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.