A well-structured, actionable instruction skill with a clear workflow and explicit stop/guard conditions, and appropriately concise for its scope. The main gap is the lack of an explicit validate-and-retry loop after the in-place doc fixes, and a procedurally-described cross-check step.

Suggestions

Add an explicit verification checkpoint after fixing drift (e.g., re-running the cross-check to confirm each flagged item now matches) to form a validate->fix->retry loop.

Give one concrete mechanism or command for the cross-check step rather than only describing the comparison procedurally.

Trim the 'Drift is the common kind of rot...' paragraph, which re-explains a concept already covered by the frontmatter description.

Dimension	Reasoning	Score
Conciseness	Mostly lean and assumes Claude's competence (lists docs surfaces, gives exact CLI commands), but a few lines restate the obvious such as explaining what 'drift' is after the frontmatter already defined it.	4 / 5
Actionability	Provides concrete, copy-pasteable commands (gh pr list, gh pr create, glab mr create) and specific file surfaces to check, but the core cross-check step is described procedurally without a concrete runnable mechanism.	4 / 5
Workflow Clarity	A clear numbered 5-step sequence with an explicit 'check for an open audit PR before opening another' guard and a stop-condition when docs already agree; missing only an explicit validate/retry feedback loop after the in-place doc edits.	4 / 5
Progressive Disclosure	Well-organized sections (What you need, Workflow, Customise, Output) with no nested references and no bundle files to misplace; the only gap is that some concrete material (example PR body template, drift report format) is inlined rather than split out, which is acceptable for a skill this size.	4 / 5
	Total	16 / 20 Passed

Description

83%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, well-structured description that clearly states both what the skill does and when to use it, with mostly concrete actions and natural trigger phrases. Minor gaps in action granularity and trigger synonyms keep it just short of exemplary.

Suggestions

Add a few natural trigger synonyms (e.g., 'stale docs', 'docs drift') so users who phrase it differently still surface the skill.

Separate the reconciliation actions more explicitly (e.g., 'detect drift, fix the docs in place, open a PR') to raise action specificity.

Tighten the 'documentation audit' framing to reduce overlap risk with generic audit/lint skills.

Dimension	Reasoning	Score
Specificity	Lists several concrete actions (check whether docs match code, open a PR with the fix) and concrete surfaces (API, commands, config), though 'open a pull request with the fix' collapses what could be multiple distinct reconciliation actions.	4 / 5
Completeness	Explicitly states what it does ('Check whether a repository's documentation still matches its code, and open a pull request with the fix when it has drifted') and when via a clear 'Use when...' clause listing three concrete trigger conditions.	5 / 5
Trigger Term Quality	Strong natural phrases a user would say ('the docs may be out of date', 'an API changed but the docs did not', 'documentation audit'), missing only a few synonyms like 'stale docs' or 'docs drift' as explicit triggers.	4 / 5
Distinctiveness Conflict Risk	The docs-vs-code reconciliation plus PR-opening niche is fairly distinct, though the broad 'documentation audit' framing carries minor overlap with general linting/CI audit skills.	4 / 5
	Total	17 / 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.

Reviewed

6 days ago

Table of Contents

Discovery Implementation Validation