Content
90%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.
An exemplary content body: terse, information-dense, and immediately executable, with a real validation step and a post-run review checklist. The only weaknesses are the absent explicit recovery loop after validate fails and one referenced file (templates/findings.md) that does not exist in the bundle.
Suggestions
Add an explicit recovery step after validation (e.g., 'If validate reports errors, regenerate the affected section and re-run validate') to close the feedback loop.
Ship templates/findings.md in the bundle or point to the section list the script itself emits, since the referenced template file is currently absent.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense operational guidance with zero padding: rules like "Cite sources for material claims. Provider payloads go in the sidecar JSON", the mode table, and exact constraints ("numResults 1-100, text.maxCharacters 1-10000") assume Claude's competence and explain no concepts it already knows. Every token carries non-obvious specifics (paths, caps, fallbacks, the 1Password op:// reference), matching the anchor 'Lean and efficient; every token earns its place'. | 5 / 5 |
Actionability | Five copy-paste-ready command invocations (report with query, report with --query-file, json, validate, doctor) at the exact CLI path, plus a mode table with concrete flags, exact output-path rules ('tmp/plans/<slug>-research.md'), and executable error recovery for a missing EXA_API_KEY. Fully executable and covers the common cases, matching the anchor for copy-paste ready commands. | 5 / 5 |
Workflow Clarity | A clear sequence is present (choose harness/tool → run report with a mode → write to the requested path → 'run validate and stop') with an explicit validation step, exit-code semantics ('exits 0 when there are no errors'), and a post-run checklist ('Read for these yourself'). It falls short of the 5 anchor because there is no explicit fix-and-retry loop: what to do when validate reports errors is implied, never instructed. | 4 / 5 |
Progressive Disclosure | The SKILL.md is a proper overview that defers detail one level deep with each reference purpose-stated: 'deep-research help lists every flag', scripts/deep-research (present in the bundle), agents/planner.md for output-path rules, and the code-quality dependency. Scored against the actual bundle, the pointer to 'templates/findings.md carries exactly the sections validate requires' dangles — no templates/ directory exists, and the section list actually lives inside the script — a minor organization gap consistent with the 4 anchor rather than the 5. | 4 / 5 |
Total | 18 / 20 Passed |