Content
35%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is a high-level, abstract template that lacks the concrete, actionable guidance needed to be truly useful. It reads more like a role description than an executable skill — there are no code examples, no specific refactoring patterns, no concrete commands, and no real validation steps. The reference to an external playbook is a good structural choice but doesn't compensate for the lack of substance in the main file.
Suggestions
Add concrete code examples showing before/after refactoring for at least 2-3 common patterns (e.g., Extract Method, Replace Conditional with Polymorphism) to make the skill actionable.
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 with concrete steps: e.g., '1. Run existing tests before changes. 2. Make one refactoring. 3. Run tests again. 4. If tests fail, revert and reassess. 5. Only proceed when green.'
Remove the redundant opening paragraph that repeats the skill description, and trim the 'Context' section which restates what's already obvious from the title and instructions.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill includes some unnecessary framing (repeating the description as the opening line, 'Context' section restating the obvious, 'Use this skill when'/'Do not use this skill when' sections that Claude can infer). However, it's not excessively verbose and stays relatively brief overall. | 2 / 3 |
Actionability | The instructions are entirely abstract and vague — 'Assess code smells,' 'Propose a refactor plan,' 'Apply changes in small slices' — with no concrete code examples, specific commands, specific refactoring patterns, or executable guidance. Everything describes rather than instructs. | 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 skill involving potentially destructive code 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 good progressive disclosure. However, the reference is mentioned twice (in Instructions and Resources) and it's unclear what that file contains or how it's structured. The main content itself could benefit from better organization — the Output Format section mixes with instructions. | 2 / 3 |
Total | 7 / 12 Passed |