Content
35%Scale 1-3Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is too abstract and high-level to be genuinely useful. It reads more like a role description than actionable instructions—lacking concrete code examples, specific refactoring patterns, or executable guidance. The workflow has a reasonable structure but needs explicit validation steps and concrete examples to be effective.
Suggestions
Add concrete, executable code examples showing before/after refactoring for at least 2-3 common patterns (e.g., Extract Method, Replace Conditional with Polymorphism).
Replace vague instructions like 'Assess code smells' with specific checklists or heuristics (e.g., 'Flag methods >20 lines, classes with >5 dependencies, duplicated blocks >3 lines').
Add explicit validation checkpoints in the workflow: e.g., 'Run existing tests after each refactoring step; if any fail, revert the last change before proceeding.'
Remove the redundant 'Context' section and the repeated role description from the opening line—Claude already knows what refactoring is.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill includes some unnecessary framing (e.g., 'You are a code refactoring expert...' repeated from description, 'The user needs help refactoring code' context section) and 'when to use/not use' sections that are somewhat verbose. However, the instructions themselves are reasonably tight. | 2 / 3 |
Actionability | The skill provides only vague, abstract guidance ('Assess code smells', 'Propose a refactor plan', 'Apply changes in small slices') with no concrete code examples, specific commands, patterns, or executable demonstrations. It describes rather than instructs. | 1 / 3 |
Workflow Clarity | There is a rough sequence (assess → plan → apply → test), but validation checkpoints are implicit ('verify regressions', 'ensure tests pass') rather than explicit with concrete steps. No feedback loops for error recovery are defined. | 2 / 3 |
Progressive Disclosure | There is a reference to `resources/implementation-playbook.md` for detailed patterns, which is good progressive disclosure. However, the main content itself is thin and vague, so the reference feels like it's compensating for missing substance rather than appropriately splitting rich content. | 2 / 3 |
Total | 7 / 12 Passed |