Content
88%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 instruction-only skill body: copy-paste commands, concrete decision rules, a gated and justified step order, and per-claim validation requirements, all carrying repo-specific knowledge Claude cannot infer. The only improvements are trimming the narrative framing and tightening the closing provenance section.
Suggestions
Trim the narrative framing in "Why the order below matters" to the minimum needed to justify the ordering — the two wrong-findings stories could each lose a sentence without losing their calibration value.
Cut or relocate the "What consumes this" section (retro / SessionEnd hook mechanics) to a reference file, keeping the two lines the run itself needs (pick-agent hand-off, retro-vs-corpus boundary) in the body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense with non-obvious domain knowledge ("median 3.6M tokens against a mean of 15.4M", the `at-open`/`confirmed` exclusion semantics, per-trap decision rules) and never explains concepts Claude already knows. But narrative framing — "This data has already produced two confident findings that were both wrong, and both were wrong the same way", "which is precisely the `cire/host` failure repeated by a different route" — is stylistic emphasis beyond bare instruction: anchor 4 (minor instances that could be trimmed). Not 3, since every section is load-bearing and repo-specific; not 5, since a few flourishes don't strictly earn their tokens. | 4 / 5 |
Actionability | Fully executable, copy-paste-ready commands throughout: `bun run --cwd tools/pr-metrics report -- --coverage/--waste/--json`, an exact `gh pr diff 882 ... | grep -E '^[+-]\s*"[^"]+":\s*"[\^~]?[0-9]'` classifier, a decision table (Small/**High**/High spend = "a hard problem that ended in a one-line fix — leave it alone"), and field-level read rules ("read the report's by line rate (`acted_on_paired - acted_on_paired_by_test`) against `control_changed`"). Anchor 5: commands plus specific decision rules covering the common cases; not 4 because even fallbacks and their caveats (queries.sql, DuckDB local-only) are specified. | 5 / 5 |
Workflow Clarity | A clearly ordered sequence (Step 0 coverage gate → Step 1 run what you need → the six traps → Step 2 report) whose ordering is itself justified, with explicit validation checkpoints: "write them down before continuing", "If nothing is rated, say so at the top of your answer", "report how many you excluded", and a per-claim falsification loop ("the number, the sample size it rests on, and what would have to be true for it to be wrong"). Anchor 5 — explicit gates and feedback loops, not 4's 'most checkpoints present'. The workflow is read-only analysis, so the destructive/batch-missing-validation cap at 3 does not apply. | 5 / 5 |
Progressive Disclosure | A single-file skill (no references/, scripts/, or assets/ bundle exists) with well-organized sections and clearly signaled, one-level-deep pointers to repo docs: "`wiki/conventions/session-metrics.md` holds the schema", "`tools/pr-metrics/README.md` has the commands". Anchor 4 (good structure, minor organization gaps): the six-traps section runs ~50 lines inline, and the closing "What consumes this" provenance section (retro/SessionEnd hook mechanics) is tangential to the run workflow. Not 5 because the >50-line body keeps everything inline and doesn't meet the single-file-5 exception; not 3 because references are clearly signaled and structure is strong. | 4 / 5 |
Total | 18 / 20 Passed |