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

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

77%

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 clear, actionable, well-sequenced methodology with an explicit verification step, scoring well on actionability and workflow clarity. Its weaknesses are moderate verbosity (framework explanation and quadrant repetition) and a lack of progressive disclosure for a fairly long single-file skill.

Suggestions

Remove or compress the framework-foundation explanation and de-duplicate the quadrant treatment between steps 2 and 3 (e.g., merge the user-need questions into the indicator lists) to tighten conciseness.

Move the detailed per-quadrant indicator lists into a references/ file (e.g. references/quadrant-indicators.md) and keep SKILL.md as a concise overview that links to it, improving progressive disclosure.

Add one short worked example (a sample page snippet with its declared-vs-inferred classification) to make the actionable guidance copy-paste ready.

Dimension	Reasoning	Score
Conciseness	The body is mostly operational (concrete indicators, quality checks, output template), but it explains framework foundations Claude already knows ("the two axes of craft (action vs cognition, acquisition vs application)...") and repeats the four quadrants across steps 2 and 3, so it could be tightened rather than earning the lean score-3 anchor.	2 / 3
Actionability	For an instruction-only analysis skill it supplies concrete, specific guidance: directory/frontmatter signals for the declared category, explicit per-quadrant indicators, named quality checks, and a copy-ready output format plus completion-status template, satisfying the actionable-but-code-exempt standard.	3 / 3
Workflow Clarity	A clearly numbered 7-step sequence (Identify → Infer → Check alignment → Note edge cases → Evaluate quality → Document misalignments → Verify completion) culminates in an explicit verification checkpoint with a status template, matching the score-3 anchor's clear sequence with validation.	3 / 3
Progressive Disclosure	It is well organized into sections (Scope, Inputs, Actions, Constraints, Output) but is a monolithic ~150-line single file with no external references, so for a >50-line skill it falls short of the score-3 anchor's well-signaled one-level-deep references and appropriate content splitting.	2 / 3
	Total	10 / 12 Passed

Description

75%

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 clearly answers both what and when with a distinctive niche, but its action verbs are abstract and its natural-language trigger coverage is somewhat narrow. Tightening specificity and adding common user phrasings would push it from good to excellent.

Suggestions

Replace abstract verbs ("Analyzes", "Identifies") with more concrete operations, e.g. 'Classifies each doc page as tutorial/how-to/reference/explanation and flags mismatches between declared and actual category.'

Broaden trigger terms to phrases users actually say, such as 'documentation structure', 'doc taxonomy', 'is this a tutorial or how-to', and 'content type audit', beyond the single 'reviewing documentation structure' clause.

Dimension	Reasoning	Score
Specificity	Names the domain ("Analyzes documentation against Diataxis framework") and several actions ("classifying content type", "Identifies misalignments"), but the verbs are abstract analytical operations rather than the concrete, varied operations the score-3 anchor exemplifies.	2 / 3
Completeness	It states what the skill does ("Analyzes documentation... Identifies misalignments between declared category and actual content") and gives an explicit when-trigger ("Use when reviewing documentation structure or classifying content type"), satisfying both halves of the score-3 anchor.	3 / 3
Trigger Term Quality	The "Use when reviewing documentation structure or classifying content type" clause offers relevant natural phrases, but coverage is thin and the niche term "Diataxis" may not be what a user spontaneously says; common variations are missing, matching the score-2 anchor.	2 / 3
Distinctiveness Conflict Risk	The Diataxis-specific framing (Tutorial, How-to, Reference, Explanation) carves a clear niche with distinct triggers unlikely to fire for unrelated skills, matching the score-3 anchor.	3 / 3
	Total	10 / 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
Commit: d1b6440

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