Content
38%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 has a clean section structure and a sensible safety/output framing, but it is an instruction shell with almost no executable substance: the workflow is a generic directive list, and the one reference that should carry the detailed patterns points to a missing file. Duplicating the description and Context sections also wastes tokens.
Suggestions
Fix or remove the dangling reference: either add resources/implementation-playbook.md with the detailed refactoring patterns, or inline a concise set of concrete techniques (e.g., extract function, replace conditional with polymorphism, characterize tests before changing code) so the skill stands alone.
Make the workflow concrete and verifiable: specify how to establish a safety net before refactoring (run existing tests, add characterization tests), how to slice changes (one refactoring per commit/diff), and an explicit feedback loop — 'if tests fail, revert the slice and re-plan' — instead of the implicit 'ensure tests pass'.
Delete the duplicated opening paragraph and the redundant 'Context' section; both restate the frontmatter description and add no guidance.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is short and mostly tight, but it duplicates the frontmatter description verbatim ('You are a code refactoring expert specializing in clean code principles, SOLID design patterns...') and then repeats the same intent again in the 'Context' section ('The user needs help refactoring code to make it cleaner...'). Two redundant sections exceed anchor 4's 'minor instances of over-explanation', though there is no teaching of concepts Claude already knows, so it is not anchor 2. | 3 / 5 |
Actionability | The instructions are high-level directives ('Assess code smells, dependencies, and risky hotspots', 'Propose a refactor plan with incremental steps', 'Apply changes in small slices') with no concrete method, commands, or worked examples, and the single pointer to substantive detail — 'open resources/implementation-playbook.md' — targets a file that does not exist in the skill bundle. This is 'high-level hints but missing the specific steps to execute', not anchor 3, because no concrete executable detail remains once the broken reference is discounted. | 2 / 5 |
Workflow Clarity | A rough sequence is present (assess → propose plan → apply in small slices → update tests and verify regressions) and 'ensure tests pass' in the Safety section acts as a checkpoint, but the checkpoints are implicit and there is no feedback loop for what to do when tests fail or behavior changes. This matches 'steps listed but validation gaps; checkpoints missing or implicit' rather than anchor 4's 'most checkpoints present'. | 3 / 5 |
Progressive Disclosure | The sections are well-organized, but the only detailed material is delegated twice ('open resources/implementation-playbook.md' in Instructions and again in Resources) to a file that does not exist — no references/, scripts/, assets/, or resources/ directories are present in the bundle. The navigation path is broken and there is no content behind the pointer, which falls below anchor 3's 'references present but not clearly signaled' (here the signal is clear but dangling, leaving the skill with no substantive payload). | 2 / 5 |
Total | 10 / 20 Passed |