Content
81%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
An exceptionally actionable, well-validated operational skill with real, well-signaled one-level-deep references. Its main weakness is token weight: the body runs ~490 lines with the depth-selection policy and several guardrails restated across multiple sections, and some protocol detail that belongs in references/ is inlined.
Suggestions
Consolidate the depth-selection policy (fast/auto/deep) into the single 'Choose when and how deeply to review' section and reference it from the other three places that currently restate it ('Checkpoints and final handoff', 'Submit and collect with --async', 'Configuration').
Move the async collection shell loop and the MCP prepared-review protocol details (stream_id construction, request_id retry semantics, result-chunk digest verification) into a references/ file, keeping only the decision rules in SKILL.md.
Deduplicate recurring guardrail phrasing ('collect every run', 'never resubmit just to poll', 'preserve context and depth') so each appears once in Guardrails rather than being restated per section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The 490-line body is dense with genuinely non-obvious product policy, but the depth-selection rules (fast/auto/deep) are restated in four separate sections ("Choose when and how deeply to review", "Checkpoints and final handoff", "Submit and collect with --async", "Configuration"), and guardrail phrases like "collect every run" and "never resubmit just to poll" recur across sections. It is below anchor 4 because the tightening opportunity is substantial, not minor, though it never explains concepts Claude already knows. | 3 / 5 |
Actionability | Fully executable throughout: copy-paste shell snippets with error branches and merge-base resolution (e.g. `review_base=$(git merge-base HEAD origin/main) || { ...; exit 1; }`), an exit-code table for async collection, a concrete JSON context schema with example values, exact flag semantics, and precise MCP field rules ("Set `review_scope.stream_id` to exactly 64 lowercase hexadecimal characters: SHA-256 of a JSON array..."). | 5 / 5 |
Workflow Clarity | The multi-step process is clearly sequenced (compatibility gate → preflight auth/base/context → choose execution path → submit → collect → present → act on findings → bounded recovery) with explicit validation at every checkpoint: version probe first, whoami before review, per-fix verify-and-re-review loops, retry-once limits, and "stop an unproductive loop" guidance for the batch-fix workflow. | 5 / 5 |
Progressive Disclosure | All seven inline reference links point to real, one-level-deep files in references/ and are well signaled at point of need (e.g. "read [shell guidance](references/windows-shells.md) before the first call"). However, the body is a near-complete manual rather than an overview — the async polling shell loop, connected-progress canonical rules, and MCP prepared-review protocol details would fit better in reference files, leaving minor organization gaps. | 4 / 5 |
Total | 17 / 20 Passed |