CtrlK
BlogDocsLog inGet started
Tessl Logo

diataxis

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

1.08x
Quality

78%

Does it follow best practices?

Impact

98%

1.08x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./diataxis/SKILL.md
SKILL.md
Quality
Evals
Security

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 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.

DimensionReasoningScore

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').

DimensionReasoningScore

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.

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
keithpatton/diataxis-agent-skill
Reviewed

Table of Contents

Is this your skill?

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.