Content
75%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 highly actionable, executable guidance with a clear investigation workflow, strong validation checkpoints, and well-integrated one-level references. Its main weakness is the verbose, tangled runtime-update policy section, which hurts token efficiency and would be better split into a reference file.
Suggestions
Move the runtime-update policy (QODO_UPDATE_BASE_URL handling, 1.x-to-2.x migration routes, latest-2 recovery) into a reference file like references/runtime-updates.md, keeping only the unadorned version probe and the 2.0.0 minimum requirement inline.
Tighten the repeated version/identity/catalog-check instructions spread across 'Runtime compatibility gate', 'Preflight', and 'Configuration' into one consolidated readiness section to reduce duplicated conditions.
Clarify the runtime-update branch by presenting the upgrade routes as a short decision list (route → precondition → command) instead of nested conditional prose.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes Claude's competence (no basic-concept padding), but the ~25-line runtime-update policy block (1.x-to-2.x routes, QODO_UPDATE_BASE_URL, channel recovery) repeats conditions across sections and embeds time-sensitive version numbers inline rather than in a reference or deprecation section. It is mostly efficient but could be meaningfully tightened, fitting the middle anchor rather than the noticeably-verbose one. | 3 / 5 |
Actionability | Guidance is fully executable: a copy-paste Quick start with exact commands and flags, a precise fallback invocation ("${QODO_HOME:-$HOME/.qodo}/bin/qodo"), a tool-group routing table, a catalog-verification command, and three worked examples showing commands plus expected cited outputs. The illustrative tool names are explicitly handled by instructing verification via `qodo read tools`. | 5 / 5 |
Workflow Clarity | The mainline workflow is clearly sequenced (choose path → version gate → preflight auth and repo resolution → route to tool group → narrow then fetch → deliver) with explicit validation checkpoints (unadorned `--version` probe, `whoami`, catalog check) and feedback loops (empty/truncated → narrow once and retry; MT-TOOL-LOOP → stop and change approach). It falls short of the top anchor because the runtime-update branch's nested conditionals create minor gaps in the overall sequence. | 4 / 5 |
Progressive Disclosure | All three bundle references (skill-updates.md, windows-shells.md, windows-launcher.md) exist, are one level deep, clearly signaled, and conditionally loaded ("launcher recovery only if invocation fails"), matching the actual bundle structure. The gap from the top anchor is the inline runtime-update policy block, which is content that belongs in a reference file like the others rather than in SKILL.md. | 4 / 5 |
Total | 16 / 20 Passed |