documentation-diataxis

Analyzes documentation against Diataxis framework (Tutorial, How-to, Reference, Explanation). Use when reviewing documentation structure or classifying content type. Identifies misalignments between declared category and actual content.

Quality

83%

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

77%Weight 40%Scale 1-3

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

A well-structured instruction-only skill with an actionable, clearly sequenced workflow and a real completion checkpoint. It loses points on conciseness (repeated quadrant listings) and progressive disclosure (a single long file with no split-out references).

Suggestions

Consolidate the four-quadrant listings: sections 2, 3, and 5 each re-enumerate Tutorial/How-to/Reference/Explanation; reference a single criteria table to reduce repetition.

Consider extracting the per-quadrant indicator checklists into a references/ file and signaling it from the body, which would both shorten SKILL.md and improve progressive disclosure.

Tighten the "Check user need alignment" section, whose per-quadrant questions largely restate the indicators already given in step 2.

Dimension	Reasoning	Score
Conciseness	The body is mostly efficient and provides Diataxis-specific criteria Claude would not already know, but the four quadrants are re-listed across sections 2, 3, and 5 and some prose could be tightened, matching the level-2 anchor.	2 / 3
Actionability	Concrete, specific guidance throughout: per-quadrant indicator checklists, concrete quality heuristics ("Paragraph length (>4 sentences)"), and a copy-ready completion status template ("✓ Diataxis analysis complete: [declared category] → [inferred category], [N] issues found").	3 / 3
Workflow Clarity	A clear seven-step sequence with an explicit "Verify completion" checkpoint (step 7) plus a completion-status checklist; the destructive/batch cap does not apply since this is a read-only analysis skill.	3 / 3
Progressive Disclosure	The skill is a single self-contained file with no bundle files (references/scripts/assets absent) and one external URL; sections are well-organized, but nothing is split out and there are no signaled one-level-deep references, matching the level-2 anchor.	2 / 3
	Total	10 / 12 Passed

Description

90%Weight 40%Scale 1-3

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

A strong, concise description with explicit trigger guidance and a clear niche. The only soft spot is specificity, which states the domain and two actions rather than a fuller list of concrete capabilities.

Dimension	Reasoning	Score
Specificity	The description names the domain and two actions ("Analyzes documentation against Diataxis framework", "Identifies misalignments between declared category and actual content") but does not enumerate multiple concrete actions, matching the level-2 anchor rather than the multi-action level-3 example.	2 / 3
Completeness	It explicitly answers what ("Analyzes documentation... Identifies misalignments") and when ("Use when reviewing documentation structure or classifying content type"), satisfying the level-3 anchor for both what and when.	3 / 3
Trigger Term Quality	Natural terms a user would say are well covered: "reviewing documentation structure", "classifying content type", "Diataxis framework", and the four category names (Tutorial, How-to, Reference, Explanation).	3 / 3
Distinctiveness Conflict Risk	The Diataxis framework is a clear niche with distinct triggers unlikely to fire for unrelated skills; it uses third person ("Analyzes", "Identifies") with no voice penalty.	3 / 3
	Total	11 / 12 Passed

Validation

100%

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 — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: canonical/copilot-collections
Path: skills/documentation-diataxis/SKILL.md
Commit: 0fe9990

Reviewed: 7 days 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.