Content
71%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.
A tight, doctrine-heavy body that is genuinely actionable — it tells the agent exactly what to ask the user, what rules bind every loop cycle, and how to recognize anti-patterns, with a clean section structure. The weaknesses are moderate: it spends a few tokens re-teaching TDD fundamentals, the loop sequence is distributed across sections with no error-recovery path, and its two referenced files (tests.md, mocking.md) are missing from the bundle, breaking the progressive-disclosure chain.
Suggestions
Include tests.md and mocking.md in the bundle (e.g., under references/) or remove the links — the body's concrete examples of good tests and mocking guidance currently point to files that don't exist.
Present the loop as one explicit ordered sequence (read CONTEXT.md → agree seams with user → red → green → repeat per slice → refactor via code-review) instead of distributing it across the 'Seams' and 'Rules of the loop' sections.
Trim the re-statements of fundamentals Claude already knows (e.g., 'TDD is the red → green loop' as an opener and 'Code can change entirely; tests shouldn't') and keep only the project-specific rules.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~30-line body is lean and directive with no padding; phrases like 'Tests verify behavior through public interfaces, not implementation details' and 'TDD is the red → green loop' restate fundamentals Claude already knows, and 'Code can change entirely; tests shouldn't' is redundant with the sentence before it. Not 5: those few tokens of over-explanation could be trimmed; not 3: the bulk is project doctrine (seam confirmation, tracer bullets, refactoring exclusion) that Claude cannot infer, not generic filler. | 4 / 5 |
Actionability | Concrete, executable guidance throughout for an instruction-only skill: a literal question to ask ("What's the public interface, and which seams should we test?"), a concrete anti-example ("expect(add(a, b)).toBe(a + b)"), a diagnostic tell ("the test breaks when you refactor but behavior hasn't changed"), a worked test-name example ("user can checkout with valid cart"), and a concrete pre-step ("read `CONTEXT.md` (if it exists)"). Not 5: no example of a full good test or a complete vertical slice in the body — those are deferred to referenced files that are not present in the bundle; not 3: the guidance is specific and directly executable, not pseudocode or high-level hints. | 4 / 5 |
Workflow Clarity | The loop sequence is clear from the rules — confirm seams with the user, red ("Write the failing test first"), green ("only enough code to pass it"), one vertical slice at a time, repeat — with an explicit validation checkpoint ("No test is written at an unconfirmed seam") and an explicit handoff for refactoring to the code-review skill. Not 5: the sequence must be assembled from four separate sections rather than stated as an ordered loop, and there is no guidance for the error path (what to do when the test won't go green or the seam proves wrong); not 3: the key checkpoints are explicit, not implicit. | 4 / 5 |
Progressive Disclosure | Good structure for a short skill: the body is a concise overview of doctrine with clearly signaled, one-level-deep references ('See [tests.md](tests.md) for examples and [mocking.md](mocking.md) for mocking guidelines') and well-organized sections. Not 5: the two referenced files are not present in the bundle (no references/ directory and no tests.md or mocking.md anywhere), so the promised examples and mocking guidelines are unreachable; not 3: what is inline is appropriately placed and the references are clearly signaled rather than buried. | 4 / 5 |
Total | 16 / 20 Passed |