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 is highly actionable — concrete commands, exact fallbacks, a routing table, and worked examples with validation checkpoints and retry loops — and its reference files are well structured with conditional one-level-deep loading. The main weaknesses are conciseness and organization: ~25 lines of runtime-update policy and repeated authorization/stop rules are inlined in the main file rather than delegated to references, which also blurs the core workflow sequence.
Suggestions
Move the runtime-update route detail (latest-2 recovery, checksum-pinned installers, per-route update policy) into a reference file like the existing references/skill-updates.md, keeping only the minimum-version probe result and stop conditions in SKILL.md — this would improve both conciseness and progressive_disclosure.
Consolidate the stop/authorization rules currently restated across 'Runtime compatibility gate', 'Preflight', 'Sandbox auth diagnostic', and 'Error Handling' into a single guardrails-adjacent section to remove repetition.
Reorder sections so the core investigation workflow (gate → preflight → route to tool group → narrow-then-fetch → deliver) is contiguous, relocating 'Handle a skill update notice' and other policy asides after it to sharpen the main sequence.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body avoids explaining known concepts and is operationally dense, but the "Runtime compatibility gate" section (~25 lines of update-route, latest-2 recovery, and checksum-pinned-installer policy) and the "Handle a skill update notice" section are inlined policy far removed from the core investigation task, and stop/authorization rules are restated across the Runtime gate, Preflight, Sandbox diagnostic, and Error Handling sections. It is not 2 because there is no basic-concept padding and most sentences carry operational content; it is not 4 because these policy blocks and repetitions are genuinely trimmable or movable to references. | 3 / 5 |
Actionability | The Quick start block gives nine copy-paste-ready commands with flags, the fallback invocation `"${QODO_HOME:-$HOME/.qodo}/bin/qodo"` is exact, preflight specifies exact commands ("qodo read whoami", "qodo tools --refresh", "qodo read codebase search-repos"), and three worked examples show full command sequences with expected results. The honesty caveat that tool names are "illustrative" is paired with a concrete verification command (`qodo read tools <group>`), so the guidance remains fully executable — matching the 5 anchor. | 5 / 5 |
Workflow Clarity | The canonical sequence (compatibility probe → preflight auth/repo resolution → route to tool group → narrow-then-fetch → deliver) is present with explicit validation checkpoints (unadorned `--version` first, whoami coverage check, `isError` before `structuredContent`, "empty or truncated → narrow once and retry") and feedback loops. It is not 5 because the top-level flow is interleaved with policy digressions (update notices, MCP/CLI dual paths, launcher recovery) that make the main sequence harder to follow linearly; it is above 3 because checkpoints are explicit and pervasive rather than implicit. | 4 / 5 |
Progressive Disclosure | The three reference files (references/skill-updates.md, references/windows-shells.md, references/windows-launcher.md) all exist, are one level deep (they link back to SKILL.md, not to further files), and are well signaled with conditional read triggers ("read only if invocation fails", "Read only for CLI commands in PowerShell or Git Bash on Windows"). It is not 5 because substantial self-contained policy content (the runtime-update routes and skill-update handling) is inlined in SKILL.md when it could be split out the way the Windows and update guides already are, diluting the overview. | 4 / 5 |
Total | 16 / 20 Passed |