Content
70%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 workflow engineering is exceptional — 20 precisely sequenced steps with layered validation gates, bounded recovery loops, and copy-paste-ready commands — but it is delivered as a 1715-line monolith that buries that quality in repetition, 200-word table cells, and reference-manual material inlined into SKILL.md. Conciseness and file organization are the clear weak points, not the guidance itself.
Suggestions
Cut the body to a step-by-step core and move the per-script documentation (the 25-row Bundled scripts table with its long output-schema cells) into a references/SCRIPTS.md, keeping one summary sentence per script inline.
Replace the ~30 repeated 'If timing mode is on, first run: step_timer.mjs mark <N>' blockquotes with a single global rule in Workflow-Wide Discipline ('at each step carrying a timing note, run mark <step> first'), which the section already half-states.
State each cross-cutting discipline rule once (never hand-edit xsi:schemaLocation, never hand-edit MUnit versions, one mvn per response) and delete the restatements inside individual steps; several steps re-explain the same rule 3-5 times.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is ~1715 lines (~53k tokens) — an order of magnitude past a reasonable SKILL.md budget — with heavy padding: the ~30 repeated 'If timing mode is on, first run: node <skill-dir>/scripts/step_timer.mjs mark N' blockquotes could be one global rule; the 'Bundled scripts' table has single cells running 200+ words (e.g. the write_maven_settings.mjs row); and rules are restated many times ('Never edit xsi:schemaLocation' / 'do not hand-edit' appears at least five times). It is domain-specific rather than generic-concept padding, so it sits above anchor 1, but it is noticeably-to-severely verbose and assumes little of Claude's intelligence. | 2 / 5 |
Actionability | Fully executable throughout: copy-paste-ready commands with exact invocations ('JAVA_HOME=$(jq -r .javaHome tmp/resolve-jdk-<target-java>.json) mvn ${MVN_SETTINGS:+-s "$MVN_SETTINGS"} clean package -DskipTests'), exact exit-code branch tables (0/1/2 semantics per gate), a failure classifier keyed to concrete error codes ('cvc-complex-type.3.2.2', 'schema_reference.4') with named fix sources, and full JSON output shapes per script. The common cases are all covered with specific commands. | 5 / 5 |
Workflow Clarity | Exemplary sequencing with explicit validation checkpoints and feedback loops: a two-phase structure with a hard approval gate ('Phase 2 MUST NOT start until Step 12's approval gate has been passed explicitly'), dedicated gates (Step 11.5 coverage gate, Step 12.0 soft dependency-tree cross-check, Step 14.5 hard pin-verification), bounded retry loops with escalation ladders ('5 build failures max', 'MUnit … 6 attempts', 'HALT via AskUserQuestion'), a completeness checklist (12.1), and 'validate → fix → re-validate' loops ('run describe_missing.mjs --phase bc again until coverage passes'). No validation gaps for the destructive/batch edits it performs. | 5 / 5 |
Progressive Disclosure | Structure within the file is clear (phases, numbered steps, Quick Reference), and the one reference — 'Use `references/llm-prompts.md §1` verbatim' — is real and well signaled. But the bulk of what should be reference material is inlined in SKILL.md: the entire 25-row script manual with per-script JSON output schemas, the Mode-A/B/C output shapes, the mvn failure-classifier tables, and the troubleshooting section — easily 1000+ lines that belong in one-level-deep reference files (the bundle ships only one reference file for 36 scripts). This matches anchor 3: some (good) structure, but content that should be separate is inline. | 3 / 5 |
Total | 15 / 20 Passed |