Content
50%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 well-structured with sensible use/skip guidance, safety constraints, and a coherent instruction arc, but it stays at a high level of abstraction — no concrete refactor techniques or examples — and its only path to depth points to a file absent from the bundle. The duplicated persona sentence and the orphaned 'Behavior preservation and evidence' caveats further reduce token efficiency and clarity.
Suggestions
Ship resources/implementation-playbook.md or remove both references to it plus the 'Behavior preservation and evidence' section that summarizes its contents — the skill's only depth path is currently broken.
Embed an explicit validation loop in the workflow, e.g. 'After each slice, run the test suite; if regressions appear, revert the slice before proceeding to the next step.'
Delete the opening persona paragraph (it duplicates the frontmatter description verbatim) and replace one abstract bullet with a small concrete before/after refactor example.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient — sections are short, and it does not explain concepts Claude already knows (no SOLID primer, no tool tutorials). However, the first body paragraph repeats the frontmatter description verbatim ('You are a code refactoring expert specializing in clean code principles...'), and the two dense 'Behavior preservation and evidence' paragraphs restate caveats about a playbook that is not in the bundle — both could be trimmed. This fits 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than the efficient anchor. | 3 / 5 |
Actionability | The Instructions give a concrete arc — 'Assess code smells, dependencies, and risky hotspots', 'Propose a refactor plan with incremental steps', 'Apply changes in small slices and keep behavior stable', 'Update tests and verify regressions' — but no specific techniques, commands, or before/after examples, and the one pointer to detail ('open resources/implementation-playbook.md') is a dead path since that file does not exist. This matches 'some concrete guidance but incomplete' rather than 'mostly executable guidance with minor gaps'. | 3 / 5 |
Workflow Clarity | A clear sequence is present (assess → plan → apply in small slices → update tests), and validation is mentioned ('Update tests and verify regressions', 'ensure tests pass'), but the checkpoints are scattered across Instructions and Safety bullets rather than embedded as explicit steps with feedback loops (e.g., run tests after each slice, revert on regression). This fits 'steps listed but validation gaps; checkpoints missing or implicit' rather than the anchor with most checkpoints explicitly in the flow. | 3 / 5 |
Progressive Disclosure | The body is well organized into clear sections and the reference is prominently signaled ('## Resources — resources/implementation-playbook.md for detailed patterns and examples'), one level deep. However, that referenced file does not exist anywhere in the bundle, and the 'Behavior preservation and evidence' section inlines dense caveat material (repository find_by_id, EmailService, execute($QUERY), CodeQL) that evidently belongs in that missing file. Structure is present but organization is undermined by the broken reference, matching 'some structure but could be better organized' rather than 'most content appropriately placed'. | 3 / 5 |
Total | 12 / 20 Passed |