review-changes

Review uncommitted or recently committed documentation changes for correctness, coherence, and style compliance. Use before creating a PR to catch issues. "review my changes", "review the diff", "check the fix before submitting", "does this look right".

Quality

81%

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

82%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 tight, well-structured review workflow with executable git commands, an explicit decision rubric, and no wasted tokens. The gaps are minor: a few described-but-uncommanded checks (grep, URL verification) and no re-review loop after changes are requested.

Suggestions

Make step 3 executable: add a concrete grep command for finding cross-references (e.g., `grep -rn "<filename-or-anchor>" content/`) instead of describing the search.

Close the feedback loop: add a brief note to re-run the review after requested changes are applied, so the workflow cycles rather than terminating at 'request changes'.

Tighten step 4's URL check with a concrete command (e.g., `curl -sI -o /dev/null -w "%{http_code}" <url>`) so every verification step is copy-paste ready.

Dimension	Reasoning	Score
Conciseness	The body is lean and assumes Claude's competence throughout: it never explains what git, diffs, or PRs are, and every explanatory sentence earns its place by justifying a non-obvious instruction ("A diff can look correct in isolation but contradict something earlier on the same page"). This matches the 'every token earns its place' anchor; it is not a 4 because there is no padding to trim.	5 / 5
Actionability	Steps 1–2 give copy-paste-ready git commands for all three comparison modes and the decision section specifies concrete output requirements. It stops short of 5 because steps 3–4 describe searches and checks ("grep for the filename, heading anchors, or key phrases", "check that it resolves") without concrete commands a reviewer could run directly.	4 / 5
Workflow Clarity	A clear seven-step sequence culminates in an explicit decision rubric (approve vs. request-changes conditions) with a concrete feedback specification ("quote the exact text that is wrong, explain why, and suggest the correct fix"), which serves as the validation checkpoint. It is not a 5 because there is no feedback loop back into the workflow — nothing instructs re-reviewing after requested changes are applied.	4 / 5
Progressive Disclosure	Sections are well-organized, self-contained, and free of nested or buried references, with no bundle files needed. It is not a 5 because the ~97-line body exceeds the sub-50-line full-inline ideal and a portion (e.g., the decision rubric or code-review checklist) could arguably live in a reference file, though nothing demands extraction.	4 / 5
	Total	17 / 20 Passed

Description

80%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 with excellent what/when completeness and natural trigger phrases. Its main weakness is distinctiveness: the trigger terms are generic diff-review phrases that overlap heavily with code-review skills despite the documentation-focused framing.

Suggestions

Differentiate the trigger phrases from generic code review, e.g. "review my docs", "check my documentation changes before the PR" — keeping "review the diff" invites conflict with a general code-review skill.

Add one or two more capability-specific triggers or synonyms (e.g., "proofread the docs", "sanity check my edits") to round out trigger term coverage.

State the review scope more comprehensively in one clause (e.g., verifying cross-references and factual accuracy, not just "correctness, coherence, and style") so the what matches what the body actually instructs.

Dimension	Reasoning	Score
Specificity	"Review uncommitted or recently committed documentation changes for correctness, coherence, and style compliance" names a concrete artifact and several specific evaluation actions (correctness, coherence, style compliance), matching the 'several specific actions; minor gaps' anchor. It falls short of 5 because it uses a single verb with criteria rather than a comprehensive list of concrete actions (e.g., cross-reference checking and factual verification covered in the body are absent).	4 / 5
Completeness	It explicitly answers both questions: what ("Review ... documentation changes for correctness, coherence, and style compliance") and when ("Use before creating a PR to catch issues"), and adds concrete trigger phrases — exactly matching the anchor for clearly and explicitly answering both with concrete triggers.	5 / 5
Trigger Term Quality	Four quoted natural phrases ("review my changes", "review the diff", "check the fix before submitting", "does this look right") give good keyword coverage with phrasing users would actually say. A few natural variants are missing (e.g., "proofread", "sanity check", "look over my docs"), keeping it below the comprehensive-synonyms anchor.	4 / 5
Distinctiveness Conflict Risk	The "documentation changes" scope carves a niche, but the trigger phrases ("review my changes", "review the diff") are exactly what a user would say when wanting a code review, and the body also handles JS/HTML/CSS changes — real overlap risk with a general code-review skill. It is not a 4 because the generic diff-review triggers would plausibly fire for closely related skills.	3 / 5
	Total	16 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	15 / 16 Passed

Repository: docker/docs
Path: .agents/skills/review-changes/SKILL.md
Commit: 4d3cbcd

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.