documentation-build

Validates documentation builds successfully. Use when checking Sphinx/RTD build integrity or diagnosing build failures. Reports errors, warnings, and build configuration issues.

Quality

84%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Low

Low-risk findings worth noting

Quality

Content

81%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 build-validation procedure with strong workflow sequencing, explicit failure/retry feedback loops, and a completion verification checklist. It is concise and assumes Claude's competence, with only minor trimming and a slightly underspecified conf.py search leaving room for improvement.

Suggestions

Replace the prose 'perform a bounded search for conf.py (max depth 4)' with a concrete command (e.g. `find . -maxdepth 4 -name conf.py`) so the actionability reaches copy-paste ready.

Tighten mildly explanatory lines like 'The `docs/` directory is the default location for Sphinx documentation' into bare directives to push conciseness to fully lean.

Note that `make -n $target` may exit 0 for some make implementations even when a target is absent; consider verifying targets against `make -p` output or a guarded dry-run that inspects stderr for 'No rule' to avoid false-positive runs.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's knowledge of Sphinx/RTD/Makefile, with purposeful code blocks and no concept padding; not a 5 because a few lines ('The `docs/` directory is the default location for Sphinx documentation', 'Check each target before running to avoid false failures') are mildly explanatory and could be trimmed.	4 / 5
Actionability	Provides concrete, executable commands (`make clean`, `make html`, a `make -n` guard loop, specific search paths and a max-depth bound) plus concrete file checks; not a 5 because the bounded `conf.py` search is described rather than given as a copy-paste command.	4 / 5
Workflow Clarity	Six clearly sequenced steps with explicit validation checkpoints: step 4 captures errors, runs `make clean`, retries once, and stops on failure, while step 6 verifies completion with a checklist and templated status strings — matching the anchor for clear sequencing with feedback loops and checklists.	5 / 5
Progressive Disclosure	Well-organized into Scope, Inputs, Actions, Constraints, and Output with no inlined material that belongs in a separate file and no bundle files present; not a 5 because there are no signaled one-level-deep references (none are strictly needed) and the Actions section is moderately long for a single-purpose skill.	4 / 5
	Total	17 / 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, third-person description that pairs a clear statement of capability with an explicit 'Use when' trigger and tool-specific keywords. It is concise, distinct, and complete, with only minor room to add synonyms or file extensions.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions — 'Validates documentation builds', 'checking Sphinx/RTD build integrity', 'diagnosing build failures', 'Reports errors, warnings, and build configuration issues' — matching the 'lists several specific actions; minor gaps' anchor; not a 5 because the actions stay slightly high-level rather than enumerating comprehensive sub-tasks.	4 / 5
Completeness	Explicitly answers both what ('Validates documentation builds... Reports errors, warnings, and build configuration issues') and when ('Use when checking Sphinx/RTD build integrity or diagnosing build failures') with concrete trigger phrases, matching the top anchor.	5 / 5
Trigger Term Quality	Includes natural terms users would say — 'documentation builds', 'Sphinx', 'RTD', 'build integrity', 'build failures' — giving good keyword coverage; not a 5 because synonyms/file extensions like 'Read the Docs', '.rst', or 'conf.py' are absent.	4 / 5
Distinctiveness Conflict Risk	Carves a clear niche (Sphinx/RTD documentation build validation) with distinct triggers and minimal overlap with other skills, matching the 'clear niche with distinct triggers; minimal conflict risk' anchor.	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-build/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.