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 skill delivers a concrete, well-validated retrieval workflow with executable commands and a clean reference bundle, and it correctly treats empty results and error paths as first-class outcomes. Its main weaknesses are token efficiency — the runtime/update edge-case material is dense run-on prose that belongs in a reference file — and presentation of the sequence, which is scattered across sections that don't match execution order.
Suggestions
Move the Runtime compatibility gate's update/recovery detail (QODO_UPDATE_BASE_URL handling, 1.x-to-2.x migration routes, checksum-pinned installer) into a reference file like the Windows guides, keeping only the version probe and minimum-version statement in SKILL.md.
Rewrite the multi-clause run-on sentences (e.g., the runtime gate and update-notice paragraphs) as short imperative steps or a numbered checklist, matching the already-effective style of the Preflight section.
Reorder sections to match execution order (Preflight → Quick start → queries → search/merge → output/apply) with edge-case sections (update notice, sandbox diagnostic) after the main path, and add a one-line concrete MCP example call with query/top_k/scopes arguments.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The core retrieval sections ("Write the queries", "Search and merge") are tight and operational with no padding of known concepts, but the ~20-line "Runtime compatibility gate" is run-on prose ("Only when the runtime needs an update, before any update check/change, test whether QODO_UPDATE_BASE_URL is set; never print its value...") that should be tightened or offloaded, and time-sensitive version stamps ("--skill-version 1.1.8", "2.0.0 or newer") are embedded in Quick start rather than isolated. Not 2 because almost every sentence carries operational instruction rather than unnecessary explanation. | 3 / 5 |
Actionability | Quick start gives copy-paste CLI commands ("qodo read rules search --query ... --top-k 20 --scopes ... --json") with a full literal example query, the query block format is fully specified with a default cross-cutting query, and the severity table maps to concrete enforcement. Not 5 because the MCP path is described in prose without a concrete example call and the "$TOPIC_QUERY"/"$SCOPE" variables in the merge examples are never bound to values. | 4 / 5 |
Workflow Clarity | A clear sequence exists (Preflight reuse check → auth/catalog → repo scope → queries → search/merge → output/apply) with explicit validation checkpoints and error-recovery loops: unadorned "--version" probe first, MCP "isError" check, whoami, catalog refresh-and-retry, low-return fallback ("< 3 rules → re-run it once with a broadened Content line"), empty-result and rate-limit handling. The operation is read-only, so the destructive-cap does not apply. Not 5 because section order diverges from execution order (update-notice and runtime gate appear before Preflight) and the dense prose makes the sequence harder to follow than a numbered checklist. | 4 / 5 |
Progressive Disclosure | All three bundle files exist (references/skill-updates.md, windows-shells.md, windows-launcher.md), are one level deep with no nested doc references, and each is clearly signaled with a read condition ("read ... before the first call", "only if invocation fails", "For user-requested updates"). Not 5 because the runtime-update/recovery procedure is inlined in SKILL.md as dense prose when it parallels exactly the kind of edge-case content already offloaded to references, leaving the main file longer than an overview needs to be. | 4 / 5 |
Total | 15 / 20 Passed |