Content
77%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.
The body is highly actionable with a well-sequenced, validated workflow and fully executable commands and prompts throughout. Its weaknesses are repetition of the review-gate rules across three sections plus non-operational roadmap content, and navigation gaps from references to non-existent shared-references files and a large inline reviewer prompt.
Suggestions
State the review-gate rules once in Step 4 and reduce the Core invariants and Key rules entries to one-line pointers, cutting the ~40 lines of repeated review/gating text.
Move the full reviewer prompt template into a reference file (e.g. references/reviewer-prompt.md) and link to it one level deep, keeping only the resolution rule and verdict handling inline.
Drop or relocate the two-phase roadmap and External alternatives section (including the time-sensitive '3000⭐ at time of writing') to a separate planning document outside SKILL.md.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The review-gate rules are restated three times ("Fresh review at the artifact boundary" in Core invariants, the full Step 4 gate, and the Key rules recap), and the Phase 2 roadmap plus External alternatives section ("3000⭐ at time of writing" — time-sensitive) are planning content rather than execution guidance. Not 4: the repetition and non-operational sections go beyond 'minor instances of over-explanation'; not 2: the bulk is dense, skill-specific operational content (resolver chain, flags, verdict handling) that Claude does not already know. | 3 / 5 |
Actionability | Everything is copy-paste executable: the full $RENDER_HTML resolver bash block, exact invocations for every option (--template, --out, --state, --json, --offline, --lang, --review/--no-review), the complete reviewer prompt, and exact output paths for verdicts and traces. Not 4: the examples cover all common cases with concrete commands — nothing remains as pseudocode or high-level hints. | 5 / 5 |
Workflow Clarity | Steps 1–5 are clearly sequenced with an explicit validation checkpoint (the Step 4 review gate: "should_review = explicit --review present or (template == 'academic' ...)"), and every verdict branch has a feedback loop — FAIL: "Tell the user the blocking issues ... and re-render. Do not silently overwrite"; WARN: deliver but surface warnings; unavailable route: "do not fabricate PASS". Not 4: validation and error recovery are explicit at each branch rather than implicit. | 5 / 5 |
Progressive Disclosure | The implementation is properly externalized (scripts/render_html.py and scripts/templates/{academic,dashboard}.html exist in the bundle and match the body's references), but three references point outside the bundle to missing files ("../shared-references/reviewer-backends.md", "../shared-references/reviewer-routing.md", "shared-references/review-tracing.md" — no shared-references directory exists), and the ~60-line reviewer prompt is inlined in the body. Not 4: dangling references and the large inline block fall short of 'references mostly clear'; not 2: sections are well-organized with clear headers and the heavy lifting lives in the bundled script. | 3 / 5 |
Total | 16 / 20 Passed |