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.
An operationally strong skill body: the iteration workflow is exemplary, with concrete commands, snapshot/revert safety, dual gates, and acceptance criteria that make it hard to execute wrong. It is dragged down by triple restatement of the same workflow (mermaid + steps + Data flow) and by a dangling REFERENCE.md reference that points to a file absent from the bundle, undercutting its own G4 gate.
Suggestions
De-duplicate the workflow: the "Data flow" section repeats the mermaid flowchart and Step Details almost one-for-one — keep one canonical representation and delete or heavily compress the others, which also fixes the false claim "Core rule — restated nowhere else in this file" (it is restated in G1/G2 and in "A worse score, ever").
Resolve the dangling reference: the body points to `REFERENCE.md` (sibling) twice but no such bundle file exists in the skill folder, violating the skill's own G4 gate — either ship REFERENCE.md with the skill or move the essential bits (seed-run evidence, rationalization counters) inline and drop the pointer.
Move version- and date-sensitive details (the "tessl 0.87 requires --workspace" quirk, the "2026-05-11 seed run iteration log" date) into a clearly labeled reference/version-notes section so the main body stays evergreen and does not penalize token efficiency.
Define or populate `${CANDIDATES[@]}` in Step 5 — the iteration loop depends on it, but no step constructs the array from the ROI-ranked table and Tessl's `.suggestions[]`.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient but the workflow is spelled out three times (mermaid flowchart, Step Details, and a largely redundant "Data flow" section) and the core rule is restated in three places ("Core rule", gates G1/G2, and "A worse score, ever") — contradicting the claim "Core rule — restated nowhere else in this file" — plus inline time/version-sensitive details ("tessl 0.87 requires --workspace", the "2026-05-11 seed run") that belong in a reference section; not 4 because the duplication is more than minor over-explanation, not 2 because there is little explanation of concepts Claude already knows. | 3 / 5 |
Actionability | Mostly executable guidance: complete bash for baselining (`tessl review run --json --workspace "$WORKSPACE"`, jq score extraction), a working `det_check` function, and a copy-paste-ready snapshot/revert iteration loop with an awk numeric gate; held below 5 because the loop iterates over "${CANDIDATES[@]}" which is never populated anywhere, `$1`/`$MAX_ITERS` are unbound in the shown context, and "apply the candidate change in-place" is a placeholder step. | 4 / 5 |
Workflow Clarity | Clear 8-step sequence with explicit validation and feedback loops throughout: upfront validation with remediation ("if it reports 'not logged in', abort and tell the user to run `tessl login`"), a per-iteration keep-or-revert gate (`SCORE_N ≥ SCORE_PREV` AND determinism not regressed), idempotent revert via `rsync -a --delete`, hard acceptance gates G1–G7, and "Any failure → revert that iteration" — matching the anchor for explicit validation steps and error-recovery loops. | 5 / 5 |
Progressive Disclosure | The body is well-sectioned and pushes evidence/logs to a one-level-deep sibling ("read `REFERENCE.md` (sibling)" appears twice), but no bundle files exist in this skill folder — no references/, scripts/, or assets/, and no REFERENCE.md — so the only cross-file reference points nowhere, violating the skill's own G4 gate; structure and reference intent are good but cannot be relied on, fitting "references present but not clearly signaled / content that should be separate is inline" better than the well-placed-content anchor at 4. | 3 / 5 |
Total | 15 / 20 Passed |