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

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

78%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, lean instruction-only skill: concrete conventions, explicit constraints, and a required verification output. Its weaknesses are minor — a redundant verification checklist and one under-specified action (verifying cross-reference resolution).

Suggestions

Replace the "Verification" checklist that re-lists every action with a shorter pointer (e.g., "Confirm all checks above ran, then state completion status") to save tokens.

Make "Verify cross-references resolve correctly" executable by specifying a method, such as a Sphinx build command (`sphinx-build -b dummy . _build`) or a grep pattern for unresolved ``:ref:`` targets.

Clarify whether the six Actions are a required sequence or parallel checks, so the workflow order is unambiguous.

Dimension	Reasoning	Score
Conciseness	The body is efficient with concrete specifics ("`connect-vscode.rst` for reST, `connect-vscode.md` for MyST"; "`:ref:` for reST, `{ref}`/`{numref}` for MyST") and no over-explanation of known concepts. The "Verification" checklist restates all six checks already detailed in Actions, which is trimmable redundancy preventing a 5.	4 / 5
Actionability	For an instruction-only skill the guidance is actionable: specific naming rules, metadata directives, reference-role preferences, and an exact output format ("`✓ Structure audit complete: [N] violations found`"). "Verify cross-references resolve correctly" provides no method or command for doing so, which keeps it from fully executable.	4 / 5
Workflow Clarity	Actions are numbered 1–6 with an explicit Verification step and a required completion-status statement, so checkpoints are present. The actions are parallel check categories rather than an ordered process with feedback loops, so the 5-anchor's error-recovery loop doesn't fit; the 3-anchor's missing checkpoints clearly doesn't.	4 / 5
Progressive Disclosure	This is a short, self-contained skill with no bundle files (no references/, scripts/, or assets/ exist) and nothing inlined that belongs in a separate file. Clean section headers (Scope, Inputs, Actions, Constraints, Output) make navigation trivial, which is appropriate disclosure for a skill this size.	5 / 5
	Total	17 / 20 Passed

Description

88%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: concrete, third-person, and comprehensive on capabilities with an explicit "Use when..." trigger clause. Its only weaknesses are a few missing natural synonyms and slight overlap risk with general documentation skills.

Suggestions

Add common trigger variations users might say, such as "docs structure", "Sphinx docs", or "documentation review", to broaden natural matching.

Sharpen distinctiveness by signaling it is a read-only structural audit (e.g., "audits" rather than the generic "Validates") to reduce overlap with documentation-writing skills.

Dimension	Reasoning	Score
Specificity	The description lists multiple concrete actions — "heading hierarchy, metadata, file naming, navigation, and cross-references" — with comprehensive coverage of the documentation-structure domain, in third person. No coverage gaps justify a 4.	5 / 5
Completeness	It explicitly answers both questions: the "what" ("Validates documentation structural integrity including...") and a concrete "when" ("Use when checking documentation organization or validating toctree structure"). The trigger phrases are specific, matching the 5-anchor rather than the merely-present "when" of the 4-anchor.	5 / 5
Trigger Term Quality	"checking documentation organization" and "validating toctree structure" are natural phrases a user would say, alongside "heading hierarchy" and "cross-references". Common variations like "docs", "Sphinx", or "documentation structure" are missing, so it falls short of comprehensive synonym coverage.	4 / 5
Distinctiveness Conflict Risk	The toctree/structural-audit niche is mostly distinct from other skills, but the broad term "documentation" creates minor overlap risk with documentation-writing or editing skills, keeping it below a 5.	4 / 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-structure/SKILL.md
Commit: d41d8d9

Reviewed: 1 day 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.