documentation-structure

Validates documentation structural integrity including heading hierarchy, metadata, file naming, navigation, and cross-references. Use when checking documentation organization or validating toctree structure.

Quality

64%

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-structure/SKILL.md

Quality

Content

66%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 skill body is concise, well-structured, and presents a clear sequential audit workflow with a verification step and explicit output contract. Actionability is the weakest area because the audit steps describe what to check rather than giving executable commands or concrete verification methods.

Suggestions

Add one or two concrete, executable verification examples (e.g. a grep/ripgrep snippet to find `:doc:` usages or to confirm a page is in the toctree) to lift actionability.

Make per-step validation explicit with a small feedback loop (detect issue -> report specific file/line -> suggest fix) rather than a single end-of-workflow completion status.

Specify how to verify cross-references resolve (e.g. run the docs build / sphinx -b linkcheck) so the verification step is actionable.

Dimension	Reasoning	Score
Conciseness	The body is well-organized and mostly lean, assuming Claude's competence without explaining what toctree or cross-references are; only minor phrasing could be tightened.	4 / 5
Actionability	Guidance is concrete in intent (verify lowercase-with-dashes, check `.. meta::`, use `:ref:`/`{ref}`) but is mostly checklist instruction rather than executable commands or code, leaving key details like how to verify cross-reference resolution unspecified.	3 / 5
Workflow Clarity	The Actions are clearly sequenced (file naming, metadata, directory placement, navigation, cross-references, verification) with a final verification step and explicit completion-status output, though the per-step validation is somewhat implicit rather than a validate-fix-retry loop.	4 / 5
Progressive Disclosure	Content is well-structured under clear section headers (Scope, Inputs, Actions, Constraints, Output) with no bundle files to reference; for an under-50-line single-purpose skill this is good organization with only minor gaps.	4 / 5
	Total	15 / 20 Passed

Description

62%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 specific, uses third person, and includes an explicit 'Use when' trigger, giving it a solid completeness and specificity profile. Trigger-term coverage and distinctiveness are good but leave room for more natural synonyms and a sharper niche boundary.

Suggestions

Add natural trigger synonyms users would actually say, e.g. 'docs', 'broken links', 'page structure', 'reST/MyST'.

Tighten the 'when' clause with a couple more concrete triggering situations (e.g. 'Use when adding a new docs page or reorganizing a toctree').

Make the niche boundary sharper by contrasting with adjacent skills (e.g. 'structural review, not prose/style review').

Dimension	Reasoning	Score
Specificity	Names the domain and lists several concrete actions (heading hierarchy, section ordering, metadata, file naming, navigation, cross-references), though the actions are structural-check categories rather than granular operations, leaving minor coverage gaps.	4 / 5
Completeness	It answers 'what' clearly and includes an explicit 'Use when checking documentation organization or validating toctree structure' clause; the 'when' is present and reasonably concrete but could name more specific triggering situations.	4 / 5
Trigger Term Quality	It includes some natural terms users would say ('documentation', 'toctree structure', 'checking documentation organization') but misses common variations and synonyms like 'docs', 'page structure', 'broken links', or 'reStructuredText/MyST'.	3 / 5
Distinctiveness Conflict Risk	The documentation-structure niche is fairly distinct from other skills, with structural-audit triggers that are unlikely to fire for unrelated skills; minor overlap risk exists with general documentation skills.	4 / 5
	Total	15 / 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-structure/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.