Content
67%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.
The body delivers genuinely executable guidance — guarded shell pipelines, exit-code semantics, and explicit validate-fix-rereview loops with bounded recovery — and its reference bundle is well-structured with real, one-level-deep files. Its main weakness is token efficiency: depth-selection policy is repeated across several sections and substantial material that belongs in reference files is inlined, making the document far longer than its actionable core requires.
Suggestions
Consolidate the depth-selection policy (fast/auto/deep criteria) into a single authoritative section; it is currently restated in 'Choose when and how deeply to review', 'Checkpoints and final handoff', 'Submit and collect', and 'Configuration'.
Move the runtime compatibility gate's update-route detail and the async collection internals (polling loop script, retry/exit-code mechanics) into reference files like the existing windows-shells.md pattern, keeping only the decision rules in SKILL.md.
Break the dense multi-clause policy sentences (e.g., in 'Checkpoints and final handoff' and 'Prepare a PR handoff') into short imperative rules or a checklist so each rule is scannable and independently enforceable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is domain-specific with almost no explanation of concepts Claude already knows, but at ~485 lines it is noticeably overlong: depth-selection policy is restated in "Choose when and how deeply to review", "Checkpoints and final handoff", "Submit and collect", and "Configuration", and sections like the runtime compatibility gate are dense run-on policy sentences that could be substantially tightened. Not score 2 because there is little true padding or generic explanation; not score 4 because the repetition and density mean real tightening is possible throughout. | 3 / 5 |
Actionability | The skill provides fully worked shell snippets — the guarded async submission pipeline with jq validation, the mktemp/trap status-polling loop, an exit-code decision table, and a concrete JSON context example — plus specific commands like `qodo read whoami --json --skill qodo-review --skill-version 1.10.15`. Not score 5: the examples are explicitly illustrative ("Confirm the exact flags with `qodo review --help`"), the merge-base line needs "substitute the intended target", and MCP arguments are deferred to the live schema, so they are not copy-paste ready across common cases. Not score 3: the code given is real and executable with error handling, not pseudocode. | 4 / 5 |
Workflow Clarity | The workflow has explicit validation checkpoints and feedback loops: bounded recovery with exit-code classification and `retry_after` handling, digest/byte-count verification for result chunks, "Batch authorized fixes, verify them, then re-review changed work", and the stop-an-unproductive-loop rule. Not score 5: the end-to-end sequence is fragmented across roughly fifteen topic sections (e.g., "Prepare a PR handoff" precedes "Instructions", the runtime gate follows "Execution"), so the reader must synthesize the order themselves; not score 3 because validation for the risky steps is present and explicit. | 4 / 5 |
Progressive Disclosure | All eight bundle files referenced in the body exist (skill-updates.md, windows-shells.md, windows-launcher.md, review-turn-context.md with its #cli-examples anchor, connected-progress.md, finding-results.md, context-delivery.md, local-triage.md), are one level deep with no nested reference chains, and are clearly signaled at point of need. Not score 5: SKILL.md itself is a ~485-line exhaustive policy document rather than a lean overview — the runtime-update gate, async collection internals, and context field semantics are prime candidates to move into reference files. | 4 / 5 |
Total | 15 / 20 Passed |