Content
73%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 exceptionally actionable and validation-rich, with ordered gates, bounded repair loops, and exact commands throughout. Its main cost is token weight: heavy duplication and run-on paragraph density, plus large inline blocks that the reference files could absorb.
Suggestions
Deduplicate the harness-compatibility rule ("If a code block below conflicts with this section, this section wins") by stating it once at the top of the compatibility section instead of three times.
Move the literal meaning-reader prompt template and the per-gate defect-code details into the existing references (report-gates.md / deliverable-phase.md), keeping only the command invocations inline.
Break the 250+ word single-paragraph directives (design-spec, V1/V2 routing, repair bounds) into bullets or tables so the same binding content costs fewer tokens and parses faster.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~194-line body is noticeably verbose: "If a code block below conflicts with this section, this section wins" is repeated three times (lines 20, 22, 24), and single paragraphs run 250+ words of nested clauses (e.g., the design-spec paragraph and the V1/V2 routing paragraph). It does not pad with concepts Claude already knows, but the duplication and run-on density leave substantial tightening potential, placing it below the mostly-efficient midpoint. | 2 / 5 |
Actionability | Guidance is fully executable: exact commands with flags ("node \"$SKILL_DIR/scripts/report-tools.mjs\" fact verify \"$SESSION_DIR/report.html\" --session-dir \"$SESSION_DIR\"", "chrome --headless --disable-gpu --no-pdf-header-footer --print-to-pdf=<out.pdf> file://<report.html>"), a literal copy-paste meaning-reader prompt with an exact verdict JSON schema, and a concrete OpenCode-to-Codex tool translation table. Copy-paste-ready commands cover the common cases. | 5 / 5 |
Workflow Clarity | The delivery workflow is explicitly sequenced with validation everywhere: "every gate for the QA tier must PASS, in order" (numbered gates 1-4 with exit-code semantics), a bounded repair feedback loop ("3 attempts, a 2-attempt plateau, an oscillation, or 15 minutes"), a success-criteria checklist, and a mandatory closing briefing. Phases 0-4 are delegated to references with explicit read-order guidance ("Read research-collection.md before scoping... then research-delivery.md before verification"), keeping the overall sequence coherent. | 5 / 5 |
Progressive Disclosure | References are one level deep, well-signaled with when-to-read conditions ("Read research-collection.md before scoping or collecting sources", "Every asset lane reads report-visualization.md first"), and every referenced path (research-collection.md, research-delivery.md, report-visualization.md, report-gates.md, deliverable-phase.md, fact-ledger.md, scripts/report-tools.mjs) exists in the bundle. However, the body still inlines ~90 lines of Phase 5/gate/meaning-verifier detail that belongs in references, so SKILL.md is not a lean overview — good structure with minor organization gaps. | 4 / 5 |
Total | 16 / 20 Passed |