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 content is highly actionable, with concrete commands, a routing table, and well-constructed worked examples backed by explicit validation gates and error-recovery loops. Its main weakness is length: repeated policy statements and inline edge-case material make it heavier than a lean SKILL.md needs to be, and the workflow sequence is scattered across interleaved policy sections.
Suggestions
Consolidate the duplicated Windows-shell and auth-denial guidance into a single section (or the existing references) — currently Windows guidance appears in both 'Execution' and 'Runtime compatibility gate', and auth-denial rules are restated across 'Instructions', 'Preflight', and 'Error Handling'.
Move the edge-case policy passages (skill update notices, sandbox auth diagnostic, launcher recovery) into the existing references/ files, keeping SKILL.md to the core MCP/CLI workflow, routing table, and examples.
Present the CLI workflow as one ordered sequence (version probe → whoami → resolve repo → route → narrow-then-fetch → deliver) so the reader doesn't have to reassemble the order from interleaved policy sections.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body never explains concepts Claude already knows and is dense with tool-specific facts, but it runs ~220 lines with repeated material (Windows-shell guidance appears in both Execution and the Runtime compatibility gate; auth-denial handling is restated across Instructions, Preflight, and Error Handling) and padded policy passages (update-notice handling, sandbox auth diagnostic) that could be tightened or moved to references. | 3 / 5 |
Actionability | The Quick start block gives copy-paste-ready commands, the routing table maps task needs to concrete tool groups, and three worked examples show exact queries with expected cited outputs; the MCP path's schema-driven flexibility is explicitly justified, and verification via `qodo read tools <group>` is specified. | 5 / 5 |
Workflow Clarity | Explicit validation gates exist (unadorned `--version` probe marked FIRST, whoami identity check, catalog refresh-once-and-retry) plus feedback loops (empty/`truncated: true` → narrow once and retry), but the sequence must be assembled from interleaved sections (update notices, sandbox diagnostics, guardrails) rather than one coherent ordered flow. | 4 / 5 |
Progressive Disclosure | All three referenced files (skill-updates.md, windows-shells.md, windows-launcher.md) exist, are one level deep, and are clearly signaled with purpose ("only if invocation fails", "for user-requested updates"); however, substantial edge-case policy remains inlined in SKILL.md instead of being split out, so placement is good but not fully appropriate. | 4 / 5 |
Total | 16 / 20 Passed |