Content
56%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 a well-structured, code-rich guide to the SPARC Refinement phase with a clearly sequenced TDD workflow and mostly executable examples, but it spends most of its tokens teaching patterns Claude already knows and inlines everything that belongs in reference files. A duplicate/stray YAML frontmatter block (name, hooks, capabilities) left in the body after line 4 adds confusion and should be removed or merged into the single real frontmatter.
Suggestions
Trim or drop the generic pattern tutorials (retry decorator, circuit breaker, complexity example) and keep only skill-specific guidance, or move them to references/error-handling.md and references/performance.md linked one level deep from SKILL.md.
Fix the code gaps that block copy-paste use: define or import sanitizeUser, generateToken, hash, SESSION_DURATION, and align the Green-phase constructor (logger) with the test setup.
Remove the stray second YAML frontmatter block (lines 6-30) from the body — or fold the hooks and capabilities into the real frontmatter — and add explicit validation commands (e.g., 'Run npm test; only proceed when green') between workflow steps.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~530-line body extensively demonstrates concepts Claude already knows — TDD red/green/refactor, retry with exponential backoff, circuit breakers, cyclomatic complexity, and a generic authentication-service tutorial — matching 'Noticeably verbose; several unnecessary explanations or padded sections'. Not a 1 because the examples are relevant to the refinement phase rather than pure conceptual padding, and not a 3 because the bulk of the code teaches familiar patterns instead of adding skill-specific knowledge. | 2 / 5 |
Actionability | Concrete, near-executable TypeScript/Jest examples dominate the body (mocked repositories, specific assertions like toHaveProperty and cache.set argument checks, a real SQL JOIN optimization, a Jest coverage config), matching 'Mostly executable guidance; concrete code or commands with minor gaps'. Not a 5 because snippets are illustrative rather than copy-paste ready — sanitizeUser, generateToken, hash, and this.SESSION_DURATION are undefined, and the Green-phase constructor requires a logger the test setup does not provide. | 4 / 5 |
Workflow Clarity | The TDD cycle (Red - write failing tests, Green - implement to pass, Refactor - keep tests green) is clearly sequenced with the test itself acting as a validation checkpoint, and performance refinement follows identify-then-optimize steps, matching 'Clear sequence with most checkpoints present'. Not a 5 because no explicit run-the-suite commands or error-recovery steps appear in the body (they exist only in the misplaced hooks block), and not a 3 because the failing-test/pass-test loop is an inherent feedback loop. | 4 / 5 |
Progressive Disclosure | Section headers (TDD Refinement Process, Performance Refinement, Error Handling Refinement, Quality Metrics, Best Practices) give the body structure, but all ~500 lines live inline in SKILL.md with no references to separate files and no bundle files exist, matching 'Some structure but could be better organized; content that should be separate is inline'. Not a 2 because the sections are clear and navigable rather than a wall of text; not a 4 because nothing is split out into reference files. | 3 / 5 |
Total | 13 / 20 Passed |