Content
20%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 reads as a generic template with abstract instructions that Claude already knows how to follow without guidance. It lacks any concrete code examples, specific refactoring patterns, or executable steps that would make it genuinely useful. The referenced implementation playbook is not provided, meaning the skill's only potential source of actionable content is missing.
Suggestions
Add concrete before/after code examples demonstrating at least 2-3 specific refactoring patterns (e.g., Extract Method, Replace Conditional with Polymorphism) so the skill provides actionable, executable guidance.
Remove the 'Context', 'Do not use this skill when', and 'Limitations' sections—these are boilerplate that Claude doesn't need and waste tokens.
Add explicit validation checkpoints to the workflow, e.g., 'Run tests after each refactoring step; if any fail, revert the last change before proceeding.'
Either provide the referenced `resources/implementation-playbook.md` bundle file or inline the key patterns and examples directly in the skill body.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is verbose and explains things Claude already knows—what code smells are, when to use refactoring, generic 'clean code' context. The 'Do not use this skill when' and 'Limitations' sections add boilerplate without actionable value. The 'Context' section restates the description. Nearly every section could be cut or tightened significantly. | 1 / 3 |
Actionability | The instructions are entirely abstract ('Assess code smells', 'Propose a refactor plan', 'Apply changes in small slices') with no concrete code examples, specific commands, patterns, or executable guidance. There is nothing copy-paste ready or specific enough to differentiate this from generic advice. | 1 / 3 |
Workflow Clarity | There is a rough sequence implied (assess → plan → apply → test), but validation checkpoints are vague ('verify regressions', 'ensure tests pass') with no explicit feedback loops or concrete verification steps. For a refactoring skill involving potentially destructive changes, this lacks the rigor needed for a score of 3. | 2 / 3 |
Progressive Disclosure | The skill references `resources/implementation-playbook.md` for detailed patterns, which is a reasonable one-level-deep reference. However, no bundle files are provided, so the reference is unverifiable and potentially broken. The main content itself is thin enough that the split feels like it's hiding the actual substance rather than organizing it. | 2 / 3 |
Total | 6 / 12 Passed |