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

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

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 review workflow with clear sequencing, checklists, and an explicit decision gate. It is slightly held back by minor motivational framing and consideration-style steps that are not strictly executable commands.

Suggestions

Trim the motivational opening framing to a single directive line to improve token efficiency.

Convert the consideration checklists in steps 3-6 into concrete commands or grep patterns where possible (e.g. a sample grep for heading anchors) to raise actionability.

Dimension	Reasoning	Score
Conciseness	The body is largely lean and command-driven, but the opening framing ('Start with no assumptions... not to rubber-stamp the diff') and a few motivational lines are mild over-explanation that could be trimmed without losing clarity, placing it just below a 5.	4 / 5
Actionability	Provides copy-paste-ready git commands and concrete grep/search guidance, but steps 3-6 are review-consideration checklists rather than executable commands, leaving minor gaps versus fully executable coverage.	4 / 5
Workflow Clarity	Seven clearly sequenced steps with bulleted checklists (cross-references, factual accuracy, code tracing) and an explicit decision gate in step 7 with approve/request-changes criteria; the destructive-operation cap does not apply to this read-only review skill.	5 / 5
Progressive Disclosure	Well-organized into seven clearly headed sections with no nested references and no external files needed; at ~108 lines it exceeds the under-50-line simple-skill exception, so it sits at good structure with minor organization gaps rather than a 5.	4 / 5
	Total	17 / 20 Passed

Description

91%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, concise description that clearly states what the skill does and when to use it, backed by natural trigger phrases. The only weakness is that several trigger terms are generic enough to occasionally overlap with code-review skills.

Suggestions

Tie the generic trigger phrases to the documentation scope, e.g. "review my doc changes", to reduce overlap with code-review skills.

Add a file-type or content cue (e.g. 'Markdown or documentation files') to sharpen the 'when' clause and boost distinctiveness.

Dimension	Reasoning	Score
Specificity	Names the domain ('documentation changes') and several concrete review actions ('correctness, coherence, and style compliance'), though the actions are all review-flavored rather than spanning distinct operation types, leaving minor coverage gaps versus a comprehensive 5.	4 / 5
Completeness	Explicitly answers both 'what' (review documentation changes for correctness, coherence, style compliance) and 'when' ('Use before creating a PR to catch issues'), reinforced with concrete trigger phrases, matching the top anchor.	5 / 5
Trigger Term Quality	Includes highly natural user utterances — "review my changes", "review the diff", "check the fix before submitting", "does this look right" — covering multiple phrasings a user would naturally say when invoking this skill.	5 / 5
Distinctiveness Conflict Risk	The documentation-changes niche is mostly distinct, but generic triggers like "review my changes" and "review the diff" carry minor overlap risk with general code-review skills, keeping it just below a 5.	4 / 5
	Total	18 / 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: ff96ad1

Reviewed: 3 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.