Content
63%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.
Operationally dense and unusually rigorous: executable CLI/JSON examples, explicit validation gates, and genuine error-recovery loops for conflicts and pagination. The costs are repetition of the update-gate rules across three sections, tangled update/recovery prose, and heavy inline conditional detail (enterprise updates, pagination, provider resolution) that should be split into reference files.
Suggestions
State the version/update-gate rules once and cross-reference them from 'Manual enterprise skill updates' and 'Runtime recovery' instead of restating them three times.
Move the enterprise skill-update, runtime-recovery, and paged-read reconstruction detail into references/ files (like the existing windows-*.md pattern), keeping SKILL.md to the trigger condition and a one-line pointer.
Add short example invocations for save-track, find-tracks, and for-pr to match the quality of the prepare-pr and bind-pr examples.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body does not tutor Claude on known concepts, but at ~450 lines it is noticeably tightened-beyond-need in places: the update-gate rules (presence-only QODO_UPDATE_BASE_URL check, 'ask once', 'never switch origins', 'one recovery attempt') are restated across 'Choose the available tools', 'Manual enterprise skill updates', and 'Runtime recovery', and dense passages like 'If the version is older or cannot be parsed... For parsed 1.x, normal qodo update can reach approved 2.x...' repeat conditions already covered. Anchor 3 ('mostly efficient but could be tightened') fits; not 2 because there is no filler explaining known concepts, not 4 because the cross-section repetition is more than minor. | 3 / 5 |
Actionability | Gives copy-paste-ready commands ('qodo --version', 'qodo read whoami --json --skill qodo-review-notes --skill-version 1.0.4 ...', 'qodo read tools review-notes --json'), a complete prepare-pr args-file JSON example, an MCP bind-pr JSON example, an operations table mapping every tool suffix, concrete field mappings ('contentMarkdown → content_markdown'), and exact pagination flags ('--read-cursor', 'prs_after', 'next_before'). Not anchor 5: several common operations (save-track, find-tracks, for-pr, publish-track) have no example invocation and defer entirely to 'discover the live schemas'. | 4 / 5 |
Workflow Clarity | Intake/resume is a clear numbered 1–5 sequence with an explicit 'ask which effort this change belongs to' checkpoint; validation gates are explicit ('check qodo --version before discovering', 'confirm localGitCapture: true', 'read the latest draft before editing', 'Wait for a durable publication receipt and ready_to_open_pr=true before opening'), and error handling defines real feedback loops (MT-CONFLICT → reread latest draft → retry with a new transport idempotency key; discard fragments and restart paged reads on conflict). Not anchor 5 because the enterprise-update and runtime-recovery sections tangle many nested exception conditions into prose that is hard to follow sequentially. | 4 / 5 |
Progressive Disclosure | The two bundle files are real, one level deep, and clearly conditionally signaled ('read [shell guidance](references/windows-shells.md) before the first call; [launcher recovery](references/windows-launcher.md) only if invocation fails'), but the SKILL.md body inlines large conditional material that belongs in separate references — the ~80-line manual enterprise update / runtime recovery procedure (needed only on update notices), the detailed pagination reconstruction rules, and the full Git-provider URL resolution cataloging. Anchor 3 ('content that should be separate is inline') fits; above anchor 2 because structure and existing references are clear, below anchor 4 because several whole sections are deferrable detail. | 3 / 5 |
Total | 14 / 20 Passed |