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

77%

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

Fix and improve this skill with Tessl

tessl review fix ./skills/documentation-diataxis/SKILL.md

Quality

Content

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

A well-structured, actionable instruction-only skill with clear sequencing and concrete classification criteria. Its main weakness is redundancy between the indicator, alignment, and verification steps, which inflates token cost without adding guidance.

Suggestions

Collapse step 3's user-need questions into step 2's indicator lists to avoid restating the same criteria twice, or move the per-quadrant indicator detail into a reference file and keep SKILL.md as an overview.

Add one short worked example (e.g., a sample page with declared vs inferred category and the resulting issue list) to make the classification and reporting workflow concrete end-to-end.

Trim step 7's verification checklist, which re-lists steps already covered in Actions, to a single completion-status statement.

Dimension	Reasoning	Score
Conciseness	Mostly efficient operational guidance, but step 3 ("Check user need alignment") largely restates the step-2 indicators as questions and step 7 ("Verify completion") restates the workflow, adding padding that could be tightened.	3 / 5
Actionability	Concrete, specific guidance throughout—per-quadrant indicator checklists, a defined issue-reporting format (location/nature/impact/suggestion), and exact completion-status templates—though it lacks worked classification examples for the common cases.	4 / 5
Workflow Clarity	Seven clearly sequenced steps with an explicit completion-verification checklist in step 7; this is an analysis (non-destructive) task so no error-recovery feedback loop is required, keeping it just below a 5.	4 / 5
Progressive Disclosure	Well-organized sections (Scope, Inputs, Actions, Constraints, Output) with a clearly signaled one-level external link, but all content lives inline in SKILL.md with no split into reference files for the lengthy indicator lists.	4 / 5
	Total	15 / 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.

A strong, well-structured description that clearly states capability, triggers, and distinctiveness with concrete actions and an explicit Use-when clause. Only minor room to expand trigger synonyms and action coverage.

Dimension	Reasoning	Score
Specificity	Names the domain and three concrete actions ("Analyzes documentation against Diataxis framework", "classifying content type", "Identifies misalignments between declared category and actual content"), but coverage stops short of the comprehensive multi-action list that defines a 5.	4 / 5
Completeness	Explicitly answers both what ("Analyzes documentation... Identifies misalignments between declared category and actual content") and when ("Use when reviewing documentation structure or classifying content type") with concrete trigger phrases.	5 / 5
Trigger Term Quality	Natural phrases like "reviewing documentation structure" and "classifying content type" plus "Diataxis framework" give good keyword coverage, but it lacks common synonyms or variations that would push it to a 5.	4 / 5
Distinctiveness Conflict Risk	The Diataxis-framework niche and explicit classification triggers make it clearly distinct from generic documentation skills with minimal conflict risk.	5 / 5
	Total	18 / 20 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: e75d6ec

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