Content
96%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 exceptionally disciplined operational skill: exact commands, verbatim-quote rules, explicit error handling, and a fully specified output format with a worked example. The only structural weakness is that everything lives inline in one file with references pointing at repo docs outside the bundle.
Suggestions
Move the detailed output-format specification (the worked reviewer-checklist example and the findings table layout) into a references/output-format.md file, keeping SKILL.md as a lean overview with a clearly signaled link.
Move the finding-to-fix table into a reference file (e.g., references/fixes.md) and link it from a one-line pointer, so the run-time instructions stay lean.
Clarify that `docs/corpus-review.md` and `docs/corpus-authoring.md` live in the corpus repo rather than the skill bundle, or bundle copies of the needed material under references/ so the skill is self-contained.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and imperative throughout ('Add no finding the tool did not emit', 'Quote the entry body verbatim', 'Report the exit code and the error verbatim') with zero concept padding. The long reviewer-checklist example is a concrete output template, not filler, so every token earns its place — matching the 5 anchor rather than the 4 anchor's 'minor instances of over-explanation'. | 5 / 5 |
Actionability | Fully executable guidance: exact commands with flags (`spectrace corpus review <spec-path> --format json`), exit-code semantics, two verbatim error strings with their meanings, exact output table column headers, a `grep -rl` lookup for corpus files, a worked checklist example, and a per-finding fix table. This meets the 5 anchor's 'copy-paste ready commands covering the common cases'. | 5 / 5 |
Workflow Clarity | The four-step workflow is clearly sequenced with JSON as the declared source of truth, and step 4 is an explicit validation checkpoint ('Every finding in the JSON appears in your output. Nothing else does.'). Error recovery is explicit ('print the error verbatim and stop') with the UnknownCitationError-vs-orphan_citation distinction spelled out. This is a read-only review skill, so the destructive/batch validation cap does not apply; the sequence matches the 5 anchor's explicit checkpoints and error-feedback handling. | 5 / 5 |
Progressive Disclosure | Sections are well-organized and the Reference section clearly signals one-level-deep docs with one-line descriptions, matching the 4 anchor's 'good structure; references mostly clear; minor organization gaps'. It falls short of the 5 anchor because the skill is a single 145-line inline body (the output-format spec and fix table could live in a reference file), it exceeds the under-50-line simple-skill exemption, and the referenced `docs/corpus-review.md` / `docs/corpus-authoring.md` are repo-relative paths not present in the skill bundle, so their content cannot be verified. | 4 / 5 |
Total | 19 / 20 Passed |