polish

Re-runnable pre-PR quality gate for the current branch. Composes two existing passes over the branch diff: a broad pr-reviewer pass (read-only review via the branch's open PR, which `pr-reviewer` requires) and a code-quality simplify pass (applies Class M mechanical refactors behind a confidence ≥ 90 % gate, reverting on failure). Run bare for the full review + simplify works; scope it with `review`, `simplify`, or the light `quick` mechanical pass. Commits each pass separately for traceability (`--no-commit` to skip). Use standalone any time mid-development to clean a branch. Note that `/create-pr` delegates its quality step to `review-loop` (the bounded convergence loop) post-draft, and the `review-loop` skill calls only `polish simplify` — never full `polish`. Triggers on "polish my branch", "clean this up before the PR", "review and simplify", "tidy up", "prep my branch", "/polish".

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 highly actionable, well-sequenced orchestration skill with concrete commands, explicit precondition and failure handling, and a clear mode/flag model. Its main weaknesses are repetition of the review-loop/create-pr relationship (stated three times) and inlining of detail that belongs in the composed skills, which costs conciseness.

Suggestions

State the review-loop/create-pr relationship once (either the intro paragraph or the end section) and drop the duplicated /create-pr and review-loop mapping tables, which describe other skills' behavior.

Move the full R35 docstring-trimming recipe detail out of Pass C — reference the code-quality skill's recipe by ID and keep only the never-delete-the-block rule inline.

Rename passes so presentation order matches the commit-section order (currently Pass A, B, D, C in Step 2 but A, B, C, D in Step 3) to remove a small navigation tax.

Dimension	Reasoning	Score
Conciseness	The body is operationally dense rather than padded with known concepts, but it repeats the review-loop/create-pr anti-circularity point three times (intro paragraph, description, and a dedicated end section with two mapping tables), and Pass C inlines the full R35 docstring-trimming recipe plus the `/create-pr` flag table — content that belongs in those other skills. This matches anchor 3's "mostly efficient but... could be tightened" rather than anchor 4's "minor instances".	3 / 5
Actionability	Guidance is fully executable: copy-paste-ready git/gh commands ("git diff --name-only origin/main...HEAD", "gh pr view --json url -q .url"), exact dispatch invocations ("Task(subagent_type=\"pr-reviewer\", ...)", "Skill(\"code-quality\", \"simplify\")"), explicit flag passthrough rules, per-pass commit messages, and a complete report template. This matches anchor 5's copy-paste-ready coverage of the common cases.	5 / 5
Workflow Clarity	Steps 0–4 are clearly sequenced with explicit validation checkpoints and error recovery: repo/default-branch guards that exit with messages, empty-diff and non-code-diff exits, three-case dirty-tree handling, per-refactor confidence gates with revert-on-failure, and skip-commit-if-no-edits logic. This matches anchor 5's "explicit validation steps; feedback loops for error recovery"; the out-of-order pass lettering (A, B, D, C) is cosmetic since passes are mode-scoped.	5 / 5
Progressive Disclosure	No bundle files exist; the single SKILL.md is well-sectioned with headers, mode/flag tables, and explicit pointers to the composed skills. However, the inlined R35 recipe detail and the `/create-pr`/`review-loop` mapping tables are content that pads the main file rather than being split out, so it fits anchor 4's "good structure... minor organization gaps" rather than anchor 5's clean overview with well-signaled separate references.	4 / 5
	Total	17 / 20 Passed

Description

88%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, highly specific description that explicitly answers both what and when, in third person, with natural trigger phrases and explicit boundary-drawing against related skills. Its only weaknesses are a few missing natural trigger variants and some overlap risk with the sibling review/simplify skills it composes.

Dimension	Reasoning	Score
Specificity	The description lists multiple concrete actions — "read-only review via the branch's open PR", "applies Class M mechanical refactors behind a confidence ≥ 90 % gate, reverting on failure", "Commits each pass separately for traceability" — covering the review, simplify, quick, and commit behaviors comprehensively. It exceeds anchor 4 (which permits minor coverage gaps) and matches anchor 5's comprehensive concrete-action coverage.	5 / 5
Completeness	Both questions are explicitly answered: the what ("Re-runnable pre-PR quality gate for the current branch. Composes two existing passes over the branch diff") and the when ("Use standalone any time mid-development to clean a branch. ... Triggers on 'polish my branch', 'clean this up before the PR'..."). This matches anchor 5, which requires both what and when with concrete trigger phrases.	5 / 5
Trigger Term Quality	Trigger phrases "polish my branch", "clean this up before the PR", "review and simplify", "tidy up", "prep my branch", and "/polish" are natural user phrasings with good variety. It falls short of anchor 5's comprehensive synonym coverage — common variants like "clean up my branch" or "get this ready for review" are absent, and much of the description is internal jargon (Class M, review-loop) rather than user-facing vocabulary.	4 / 5
Distinctiveness Conflict Risk	The description carves a clear pre-PR branch-cleanup niche and explicitly disambiguates from siblings ("the `review-loop` skill calls only `polish simplify` — never full `polish`"). However, triggers like "review and simplify" and "tidy up" overlap with the closely related `code-quality` and `pr-reviewer` skills it names, matching anchor 4's "minor overlap risk with closely related skills" rather than anchor 5's minimal conflict risk.	4 / 5
	Total	18 / 20 Passed

Validation

87%

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

Validation for skill structure

Criteria	Description	Result
metadata_field	'metadata' should map string keys to string values	Warning
frontmatter_unknown_keys	Unknown frontmatter key(s) found; consider removing or moving to metadata	Warning

	Total	14 / 16 Passed

Repository: mthines/agent-skills
Path: skills/quality/polish/SKILL.md
Commit: 39b3f44

Reviewed: 22 hours 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.