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

86%

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

85%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, executable workflow: concrete bash commands, a bounded fallback search order, severity categorization, and an explicit capture-clean-retry-stop feedback loop with a hard completion gate. Weak spots are minor — the conf.py search lacks a runnable command, and the completion-status formatting in step 6 could be trimmed.

Suggestions

Provide the executable command for the bounded conf.py search (e.g., 'find . -maxdepth 4 -name conf.py') alongside the existing bash blocks.

Trim step 6: one completion status line plus the checklist is enough; the three enumerated status strings are redundant with the Output section.

Dimension	Reasoning	Score
Conciseness	Lean body that assumes competence — no explanation of what Sphinx is, direct commands, tight Constraints section. Not 5 because step 6's completion-checklist and triple status-string formats edge into over-specification; not 3 because padding is minor and localized.	4 / 5
Actionability	Copy-paste-ready bash for the core build ('make clean / make html') and a concrete guard loop ('if make -n $target 2>/dev/null; then make $target; fi'). Not 5 because the bounded 'search for conf.py (max depth 4)' is described but not given as an executable command; not 3 because guidance is largely executable, not pseudocode.	4 / 5
Workflow Clarity	Numbered six-step sequence with an explicit feedback loop: capture full output, 'make clean' to reset, retry once, 'STOP and report all captured errors' if the retry fails, and a hard gate ('Do not proceed to content analysis until build succeeds'), plus a completion-verification checklist. Matches anchor 5 including error-recovery loops.	5 / 5
Progressive Disclosure	No bundle files exist; the single-file body is well-sectioned (Scope/Inputs/Actions/Constraints/Output) and nothing clearly belongs in a separate file. Not 5 because at ~95 lines the structure is good rather than an exemplar of split content with clearly signaled navigational references; not 3 because organization is clean with no buried content.	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 description: third-person, concrete, with an explicit 'Use when...' trigger clause naming Sphinx/RTD build integrity and build-failure diagnosis. The only gaps are minor — a few natural synonyms (e.g., 'Read the Docs', 'docs build', 'build warnings') would round out trigger coverage.

Suggestions

Add natural trigger synonyms such as 'Read the Docs', 'docs build', or 'build warnings' to broaden keyword coverage.

Mention one more concrete capability, e.g., running Sphinx build targets and categorizing findings by severity, to lift specificity toward comprehensive coverage.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions ('Validates documentation builds', 'diagnosing build failures', 'Reports errors, warnings, and build configuration issues') in third person, but coverage is not fully comprehensive — running build targets and severity categorization from the body are absent. Not 5 because anchor 5 requires multiple actions with comprehensive coverage; not 3 because there are more than 1-2 concrete actions.	4 / 5
Completeness	Clearly 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. Explicitly matches anchor 5; not 4 because the when-clause is explicit and multi-condition, not merely present-but-imprecise.	5 / 5
Trigger Term Quality	Includes natural terms users would say: 'Sphinx', 'RTD', 'build integrity', 'build failures'. Not 5 because common variations are missing ('Read the Docs' spelled out, 'docs build', 'build warnings', 'conf.py'); not 3 because coverage goes beyond 'some relevant keywords' with multiple natural phrases.	4 / 5
Distinctiveness Conflict Risk	'Sphinx/RTD build integrity' carves a clear niche with distinct triggers (build validation vs. docs authoring/editing), so conflict risk with other documentation skills is minimal. Fits anchor 5; not 4 because there is no meaningful overlap with closely related skills.	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: 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.