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.
A dense, highly actionable procedural skill with real commands, a worked example query, explicit error-recovery loops, and well-managed one-level references. Its main weakness is verbosity: the runtime-compatibility and update-policy prose is tortuous conditional text that would be tighter and better placed in a reference file.
Suggestions
Move the deployment-approved 1.x→2.x upgrade-route policy (the long 'Runtime compatibility gate' paragraphs) into a dedicated reference file like references/runtime-updates.md, keeping only the version-probe command and the stop conditions inline.
Convert the run-on conditional sentences in Preflight step 2 and the update-notice section into short bulleted decision rules (condition → action) to cut token cost without losing constraints.
Add one worked example of the MCP `rules-search` call with its JSON arguments, since the Quick start currently illustrates only the CLI path.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Every sentence carries a distinct constraint and it assumes Claude's competence, but sections like "Runtime compatibility gate" are noticeably verbose run-on policy prose ("This exception covers only deployment-approved 1.x to stable 2.x; it does not authorize other major migrations...") that could be tightened or moved to a reference file. Mostly efficient with clear room to trim, matching the 3 anchor better than the padded 2 or the lean 5. | 3 / 5 |
Actionability | The Quick start gives copy-paste-ready commands (`qodo --version`, `qodo read whoami --json --skill ...`, a fully worked multi-line `rules search` query with `--top-k 20 --json`), plus concrete scope-parsing examples (`git@host:a/b` → `a/b`). Minor gaps keep it below 5: the MCP path has no worked example call, and some guidance (severity table application, output pattern) is instructive rather than executable. | 4 / 5 |
Workflow Clarity | A clear sequence exists — Preflight (reuse → auth/catalog → repo scope) → write queries → search and merge → output and apply — with explicit checkpoints (unadorned version probe first, check `isError`, `No tool catalog cached` refresh-once-and-retry) and feedback loops (broadened low-return re-query, re-probe after update). Below 5 because the steps are spread across many interleaved sections with forward/backward cross-references that make the overall order harder to follow. | 4 / 5 |
Progressive Disclosure | All three bundle files (references/skill-updates.md, windows-shells.md, windows-launcher.md) are real, one level deep, and clearly signaled with conditional load triggers ("only if invocation fails", "before the first call"). Good structure overall, though the long inline runtime-update policy in the main body is content that arguably belongs in a reference, matching the 4 anchor's "minor organization gaps". | 4 / 5 |
Total | 15 / 20 Passed |