Content
81%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.
A well-engineered workflow skill: the phased process is unambiguous, rich in validation checkpoints and feedback loops, with fully executable commands and a complete worked example. The main costs are token efficiency — duplicated smell/mapping tables and a metadata trailer — and a dangling reference to a missing templates/refactoring-plan.md file.
Suggestions
Trim the 10-row 'Quick Reference' smell table and the smell-to-refactoring mapping table (or collapse them to 3–4 rows) since the full catalogs live in references/code-smells.md and references/refactoring-catalog.md; keep only the link plus a one-line pointer.
Create templates/refactoring-plan.md or remove both references to it — the body cites it in Phase 4 and in the References section, but the file is absent from the bundle.
Delete the closing metadata block ('Version History', 'Last Updated', 'Claude Code Version', 'Compatible Models') and the 'What Are Code Smells?' explainer — neither changes what Claude does and both spend context on concepts Claude already knows.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is mostly efficient — phases, checklists, and commands earn their tokens — but includes unnecessary material: a full 10-row smell table and a 10-row smell-to-refactoring table that duplicate references/code-smells.md and references/refactoring-catalog.md, a 'What Are Code Smells?' explainer Claude does not need, and a trailing metadata block ('Version History', 'Compatible Models', 'Claude Code Version'). This is 'mostly efficient but includes some unnecessary explanation or could be tightened' (anchor 3); it is not anchor 2 because the padding is localized rather than pervasive, and not anchor 4 because the duplicated tables alone represent a substantial trim opportunity. | 3 / 5 |
Actionability | Fully executable guidance throughout: copy-paste commands ('find . -name "*test*"', 'pytest -v', 'python scripts/detect-smells.py <file>', 'python scripts/analyze-complexity.py <file>'), concrete commit-message examples, a complete before/after worked example, and specific per-phase outputs and user prompts. This matches anchor 5 ('fully executable; copy-paste ready code or commands; specific examples cover the common cases'); score 4 would require minor gaps, and none are evident. | 5 / 5 |
Workflow Clarity | The six-phase workflow is explicitly sequenced (with an ASCII flow diagram) and saturated with validation checkpoints: 'STOP. Fix failing tests before refactoring', the 'Change → Test → Green? → Commit → Next step' rhythm, 'If tests fail (red) - STOP immediately - Undo the change', approval gates per phase, and a post-refactoring checklist with before/after metrics. This matches anchor 5 (explicit validation steps, feedback loops for error recovery, checklists); it exceeds anchor 4, which allows minor validation gaps. | 5 / 5 |
Progressive Disclosure | Good structure: the body is an overview with well-signaled one-level-deep links to references/code-smells.md, references/refactoring-catalog.md, and the two scripts, all of which exist. It is anchor 4 rather than 5 because [templates/refactoring-plan.md](templates/refactoring-plan.md) is referenced twice but the file does not exist in the bundle, and because the inline quick-reference tables restate content that already lives in the reference files. It is above anchor 3 because the references that do exist are clearly signaled and the split is otherwise appropriate. | 4 / 5 |
Total | 17 / 20 Passed |