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.
A dense, highly actionable instruction body with executable commands, explicit validation gates, and a well-organized one-level-deep reference bundle. Its main cost is token weight: repeated policies and stale-prone hardcoded versions inflate length without adding capability.
Suggestions
Consolidate the reuse rule stated in both Instructions and Preflight and the "empty result is valid" note repeated across Preflight, Search and merge, Error Handling, and Guardrails into a single authoritative location.
Move the skill-update notice policy and sandbox auth diagnostic into a reference file (e.g. references/skill-updates.md), keeping only a one-line routing pointer in the body, and cite windows-shells.md once instead of three times.
Replace the hardcoded "--skill-version 1.1.7" and repeated "2.0.0 or newer" stamps with a single version-reference line or move them to the update/compatibility reference so they stay maintainable.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly contract-specific detail Claude cannot know (flags, gates, error semantics), but the ~235-line body repeats policies across sections (reuse stated in both Instructions and Preflight, "unadorned version probe" four times, empty-result-is-valid in four places) and hardcodes time-sensitive versions ("Qodo CLI 2.0.0 or newer", "--skill-version 1.1.7" inline), which could be tightened. Not a 2 because nothing explains concepts Claude already knows; not a 4 because the repetition and stale-prone version stamps are noticeable. | 3 / 5 |
Actionability | Fully executable CLI commands with exact flags ("qodo read rules search --query ... --top-k 20 --scopes "/owner/repo/" --json"), a literal complete example query, the fallback invocation "${QODO_HOME:-$HOME/.qodo}/bin/qodo", and a concrete severity-enforcement table. The MCP path has no example call, but that flexibility is explicitly justified ("MCP uses the host-provided inputSchema"). | 5 / 5 |
Workflow Clarity | The multi-path workflow has explicit validation checkpoints and bounded feedback loops — the unadorned version gate with stop conditions, "Check isError, then read structuredContent", one-bounded catalog refresh, and the "re-run it once with a broadened Content line" fallback. Falls short of 5 because the sequence must be stitched from eight interleaved sections (Quick start before Preflight, runtime gate and update-notice sections interleaved) via prose cross-references rather than a single linear order. | 4 / 5 |
Progressive Disclosure | The bundle is well structured: three one-level-deep references (references/skill-updates.md, windows-shells.md, windows-launcher.md) that all exist, are clearly signaled, and are purpose-scoped ("Read only when no verified installed native invocation works"). Minor gaps: some policy detail that could live in references (update-notice handling, sandbox auth diagnostic) is inlined, and windows-shells.md is linked three times. | 4 / 5 |
Total | 16 / 20 Passed |