CtrlK
BlogDocsLog inGet started
Tessl Logo

diataxis

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

1.10x
Quality

100%

Does it follow best practices?

Impact

97%

1.10x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No known issues

SKILL.md
Quality
Evals
Security

Quality

Content

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 exemplifies good documentation practices while teaching them. It provides a complete, actionable overview with the compass matrix, type-specific principles, a clear workflow, a worked example, and a common mistakes table — all without unnecessary verbosity. The progressive disclosure to 12 reference files is well-organized and clearly signaled.

DimensionReasoningScore

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), the guidance is highly specific and directly applicable.

3 / 3

Workflow Clarity

The 'How To Apply' section provides a clear 5-step sequence with an implicit validation checkpoint ('Check for type mixing'). The worked example reinforces the workflow by walking through all steps. The compass questions serve as a decision tool. For a non-destructive documentation task, this level of workflow clarity is excellent — no batch/destructive operations require feedback loops.

3 / 3

Progressive Disclosure

Excellent progressive disclosure structure. The main file provides a complete, usable overview with concise bullet points for each type, then clearly signals 12 one-level-deep reference files organized in a navigable table. References are consistently formatted ('Load `references/X.md` for full guidance') and cover logical subtopics. No nested references or monolithic walls of text.

3 / 3

Total

12

/

12

Passed

Description

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 what the skill does (structure, classify, and write docs using Diátaxis), when to use it (comprehensive trigger scenarios), and what makes it distinctive (the specific Diátaxis framework). It uses proper third-person voice, includes abundant natural trigger terms, and has explicit 'Use when' guidance covering both primary and secondary use cases.

DimensionReasoningScore

Specificity

Lists multiple concrete actions: 'structure', 'classify', 'write documentation', 'improve documentation', 'restructure docs', 'decide what type of doc to write', 'classify existing content'. Also names the specific framework (Diátaxis) and the four document types it covers.

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', 'improve documentation'. These are all terms a user would naturally use when seeking documentation help.

3 / 3

Distinctiveness Conflict Risk

The Diátaxis framework is a specific, well-defined niche that clearly distinguishes this from generic writing or coding skills. The focus on documentation architecture, classification into four types (tutorials, how-to guides, reference, explanation), and the named framework make it highly distinctive and unlikely to conflict with other skills.

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.

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository
joshuadavidthomas/agent-skills
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.