CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

67

Quality

80%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

73%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 a clear 7-step sequence and explicit verification. The main weaknesses are redundancy between the classification criteria (step 2) and the user-need alignment checks (step 3), and no worked example of the final report format.

Suggestions

Merge the step 3 user-need alignment questions into the step 2 indicator lists (or reduce step 3 to a one-line mapping) to remove the duplicated criteria and cut token cost.

Add a brief worked example of the completion-status line and one or two sample report findings to make the output format unambiguous.

Consider moving the four-quadrant indicator checklists and deep-quality criteria into a single one-level reference file (e.g., references/criteria.md) to keep SKILL.md as a lean overview.

DimensionReasoningScore

Conciseness

Mostly efficient operational checklists, but step 3 'Check user need alignment' substantially duplicates the step 2 classification criteria (e.g., 'Is it a learning-oriented lesson? Does it build confidence through doing? Is it linear and safe?' restates the tutorial indicators), so it could be tightened. Fits the 'mostly efficient but includes some unnecessary explanation or could be tightened' anchor; not 4 because the redundancy is more than minor, not 2 because the material is not padded and assumes domain knowledge.

3 / 5

Actionability

Concrete, executable guidance for an instruction-only skill: specific indicator checklists per quadrant, per-issue reporting requirements (location, nature, impact, suggestion), and a literal completion-status format ('✓ Diataxis analysis complete: ...'). Not 5 because there is no worked example of a classification or a sample report snippet; not 3 because the guidance is specific rather than pseudocode-like or incomplete.

4 / 5

Workflow Clarity

A clearly sequenced 7-step workflow with an explicit verification step (step 7 'Verify completion') that functions as a checklist, plus a required completion-status statement. This matches the top anchor ('explicit validation steps... checklists for complex processes'); the destructive/batch cap does not apply since this is read-only analysis.

5 / 5

Progressive Disclosure

The body is well-organized (Scope, Inputs, Actions, Constraints, Output) with no nested references and no bundle files. It fits 'good structure; most content is appropriately placed; minor organization gaps'; not 5 because at ~148 lines the per-quadrant indicator lists and quality criteria are moderately bulky inline content that could be split into a one-level reference file, and not 3 because everything present is needed at execution time and clearly signaled.

4 / 5

Total

16

/

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 description: third-person, concise, names the specific framework, lists concrete actions, and includes an explicit 'Use when' trigger clause. Only minor room to improve via broader synonyms such as 'technical writing' or 'docs review'.

DimensionReasoningScore

Specificity

"Analyzes documentation against Diataxis framework" and "Identifies misalignments between declared category and actual content" name the domain and several concrete actions, with minor gaps (e.g., no mention of producing recommendations/reporting output). This matches the 'several specific actions; minor gaps' anchor; not 5 because coverage is not comprehensive, not 3 because more than 1-2 actions are explicitly stated.

4 / 5

Completeness

Explicitly answers both: what ("Analyzes documentation against Diataxis framework... Identifies misalignments between declared category and actual content") and when ("Use when reviewing documentation structure or classifying content type") with concrete trigger phrases. Matches the top anchor exactly; a missing or weak 'Use when' clause would cap it at 3, which is not the case here.

5 / 5

Trigger Term Quality

"reviewing documentation structure" and "classifying content type" are natural user phrases, plus the four category names (Tutorial, How-to, Reference, Explanation) as domain keywords. Not 5 because common synonyms users might say ("technical writing", "docs", "information architecture") are missing; clearly above 3's 'some relevant keywords but missing variations'.

4 / 5

Distinctiveness Conflict Risk

"Diataxis framework" names a clear niche with distinct triggers unlikely to fire for generic documentation or PDF skills. Minimal conflict risk; matches the 'clear niche with distinct triggers' anchor rather than 4, which would require minor overlap with closely related skills.

5 / 5

Total

18

/

20

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.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository
canonical/copilot-collections
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.