documentation-review

Performs comprehensive documentation review including build validation, Diataxis analysis, structure audit, accuracy verification, and style compliance. Use when reviewing documentation changes or auditing documentation quality.

Quality

81%

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

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-orchestrated workflow with excellent sequencing, explicit validation gates, decision points, and thorough error handling, all correctly delegating atomic work to named skills and splitting the report format into a verified reference file. The main cost is token efficiency: the checkpoint/verification boilerplate is stated in the Execution Requirements block and then repeated nearly verbatim in all seven stages, roughly doubling the content that a single template definition would cover.

Suggestions

Remove the per-stage 'Checkpoint:' lines and the repeated 'Verify:' statements — the Execution Requirements block already defines the single checkpoint template and the confirm-capture-record rule, so each stage only needs its unique inputs and outputs.

Replace the seven per-stage 'Execute/Capture/Verify/Checkpoint' sub-blocks with a compact table (Stage | Skill | Input | Output) to keep the same guidance at a fraction of the tokens.

State where the atomic skills (documentation-build, documentation-diataxis, documentation-structure, documentation-verify, documentation-style) live or how they are resolved, so the orchestration is executable even if the skills are not already in the agent's context.

Dimension	Reasoning	Score
Conciseness	The checkpoint template ('✓ Stage [N] complete: [skill-name] generated [N] findings') is defined once in Execution Requirements and then re-specified in every stage, and each stage's 'Verify:' line restates the CRITICAL block. Mostly efficient content, but the repeated boilerplate could be tightened — not a 4 because the repetition is more than minor.	3 / 5
Actionability	The orchestration is concrete: named atomic skills per stage ('Use the `documentation-build` skill'), a skill-to-report-section mapping table, exact checkpoint strings, and specified error-handling paths. It is not a 5 because it never states how or where the atomic skills are resolved (paths or invocation mechanics).	4 / 5
Workflow Clarity	Seven explicitly sequenced stages with verify-before-proceed gates ('Do NOT proceed to Stage [N+1] until Stage [N] is verified complete'), a STOP decision point on build failure, per-stage checkpoints, and a dedicated Error Handling section with recovery and fallback paths. This matches the top anchor: clear sequence, explicit validation, and feedback loops for error recovery.	5 / 5
Progressive Disclosure	The report format is appropriately split into a real, clearly signaled, one-level-deep reference (references/doc-review-report-template.md, which exists in the bundle), and the body is well-sectioned with headers. It is not a 5 because the ~200-line body carries per-stage checkpoint boilerplate that could be compressed, leaving the overview less lean than the anchor's clear-overview ideal.	4 / 5
	Total	16 / 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 that clearly states both what the skill does (five enumerated review capabilities) and when to use it (two explicit trigger scenarios), written in third person. The only weakness is modest trigger-term coverage — it lacks common synonyms such as 'docs' or 'documentation audit' that users might naturally say.

Dimension	Reasoning	Score
Specificity	The description enumerates five concrete actions — 'build validation, Diataxis analysis, structure audit, accuracy verification, and style compliance' — giving comprehensive coverage of the workflow. It is not a 4 because there are no gaps in the action list relative to the skill's scope.	5 / 5
Completeness	It explicitly answers both: the 'what' via the five-part capability list and the 'when' via a concrete 'Use when reviewing documentation changes or auditing documentation quality' clause. The 'when' is explicit with concrete trigger phrases, matching the top anchor rather than the weaker 'when' of a 4.	5 / 5
Trigger Term Quality	'reviewing documentation changes' and 'auditing documentation quality' are natural phrases users would say. It falls short of the 5 anchor because common synonyms like 'docs review', 'documentation audit', or 'doc style check' are absent.	4 / 5
Distinctiveness Conflict Risk	Documentation review is a clear niche with distinct triggers, but 'reviewing documentation changes' could overlap with a generic code-review skill when diffs touch docs. Mostly distinct with minor overlap risk against closely related review skills.	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-review/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.