Content
81%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 strong operational skill body: concrete executable commands, a clearly gated workflow with dry-run/verification checkpoints for all destructive and batch operations, and correct use of a one-level-deep reference for the enterprise update procedure. The main weaknesses are moderate length from repeated approval language across sections and several inlined edge-case procedures that would fit better as reference files.
Suggestions
Consolidate the approval/confirmation rules stated in 'Instructions', the per-job bold text, and 'Guardrails' into the single Guardrails section to remove repetition and trim tokens.
Move the edge-case procedures that only fire in narrow situations — 'Handle a skill update notice', 'Sandbox auth diagnostic', and the 'Where rules come from' provenance explainer — into one-level-deep files under references/, like the existing skill-updates.md pattern.
Add one fully worked `qodo rules create` example with realistic values (name, category, severity, content, scopes) so the create path is copy-paste ready rather than placeholder-only.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with genuinely non-obvious operational knowledge (CLI fallbacks, platform behavior, error codes) and avoids teaching concepts Claude already knows, but approval/confirmation language recurs across "Instructions", "The four jobs", and "Guardrails" (e.g. "Reuse explicit approval... otherwise get confirmation" vs "Require approval for the exact write... A dry run is not authorization"), and the opening "Instructions" paragraph is an abstract summary of sections that follow. These minor repetitions could be trimmed, matching the level-4 anchor rather than the every-token-earns-its-place level-5 anchor. | 4 / 5 |
Actionability | The Quick start gives copy-paste-ready commands for every job (create, update, set-state, set-scope, list, bulk, get, tools) plus concrete POSIX/PowerShell launcher fallbacks, and Error Handling maps specific outcomes ("MT-RATE-LIMITED", permission-denied, validation error) to specific next actions. However, command arguments are placeholders ("--name \"...\""), examples are illustrative and must be re-verified against the live catalog, and there is no fully worked example with realistic values — minor gaps that sit between the level-4 and level-5 anchors, settling at 4. | 4 / 5 |
Workflow Clarity | The sequence is explicit and gated: unadorned version probe → preflight (auth/catalog, resolve target, derive scope) → routed job → verified-outcome reporting, with validation checkpoints exactly where the rubric wants them: "--dry-run → show the count/blast radius → confirm → real call" for bulk/destructive ops, read-back after uncertain mutations ("after a timeout or transport failure, read back the target before retrying"), state verification in the create response, and error-recovery loops (validation error corrected once within approved intent). This matches the level-5 anchor including feedback loops for destructive/batch operations. | 5 / 5 |
Progressive Disclosure | Structure is good: clear section headers, a Quick start up front, and the one deep-dive topic (enterprise updates) correctly pushed to a well-signaled one-level reference — "follow the [manual-update procedure](references/skill-updates.md)" — which exists and is 15 lines, one level deep. However, the ~270-line body still inlines substantial edge-case material (skill-update notice handling, sandbox auth diagnostics, the sourceType provenance explainer) that could similarly live in reference files, keeping it at the level-4 anchor ('most content appropriately placed; minor organization gaps') rather than the cleanly split level-5 anchor. | 4 / 5 |
Total | 17 / 20 Passed |