diataxis

Write, review, or organize documentation following the Diátaxis framework. Use when writing docs, reviewing docs, creating tutorials, how-to guides, reference material, or explanatory content.

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

90%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a well-structured, concise framework overview with strong actionability via lookup tables and clear write/review workflows. The main gap is that the referenced source-material bundle cannot be confirmed alongside SKILL.md, slightly capping progressive disclosure.

Suggestions

Ensure the diataxis-documentation-framework/ source directory with the referenced .rst files is bundled under references/ (or another standard bundle dir) so the navigation table points to verifiable files.

Strengthen the writing workflow's verify step into an explicit feedback loop (e.g. re-classify each section after edits and re-check for mode drift) to lift workflow clarity from a soft check to a hard checkpoint.

Pin the source-material location with an absolute or skill-relative path convention that is resolvable at runtime, since ${CLAUDE_SKILL_DIR}/diataxis-documentation-framework/ is not visible in this review layout.

Dimension	Reasoning	Score
Conciseness	Lean and efficient: the compass table and mode summaries are the skill's core framework content rather than padding, and it avoids explaining concepts Claude already knows; every section earns its place.	5 / 5
Actionability	Instruction-only but highly actionable: a compass classification table plus a task→source-file lookup table give concrete, copy-paste-ready guidance on exactly which .rst page to read for each documentation task.	5 / 5
Workflow Clarity	Clear numbered sequences for both writing (Classify→Read→Write→Verify) and reviewing (Classify→Read→Assess→Report) with an explicit mode-mixing verify step, but the validation is a single soft check rather than a hard validate-and-retry loop.	4 / 5
Progressive Disclosure	Well-signaled one-level-deep navigation via a task→.rst-file table with clear 'do not read HTML/images' guidance, but the referenced bundle directory is not present in the standard references/scripts/assets dirs to verify the files exist.	4 / 5
	Total	18 / 20 Passed

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is strong: it states concrete actions, gives explicit 'Use when' triggers enumerating the four documentation modes, and is anchored to a distinctive named framework. Only minor gains are available in trigger synonym coverage and listing more granular actions.

Dimension	Reasoning	Score
Specificity	Names the domain and three concrete verbs ('Write, review, or organize documentation'), fitting 'lists several specific actions; minor gaps' rather than the comprehensive multi-action coverage of anchor 5.	4 / 5
Completeness	Explicitly answers both 'what' (write/review/organize docs per Diátaxis) and 'when' ('Use when writing docs, reviewing docs, creating tutorials, how-to guides, reference material, or explanatory content') with concrete trigger phrases.	5 / 5
Trigger Term Quality	Strong natural phrasings ('writing docs', 'tutorials', 'how-to guides', 'reference material', 'explanatory content') covering the four canonical modes, with a few synonyms (e.g. 'explaining', 'onboarding docs') missing, so just below anchor 5.	4 / 5
Distinctiveness Conflict Risk	Tied to the named Diátaxis framework with the four distinct documentation modes as triggers, giving a clear niche with minimal conflict risk.	5 / 5
	Total	18 / 20 Passed

Validation

87%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 14 / 16 Passed

Validation for skill structure

Criteria	Description	Result
allowed_tools_field	'allowed-tools' contains unusual tool name(s)	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: oxidecomputer/claude-plugins
Path: eng/skills/diataxis/SKILL.md
Commit: 7bd491a

Reviewed: 1 day ago

Table of Contents

Discovery Implementation Validation

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.