Content
86%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.
An unusually disciplined instruction-only skill body: terse, expert-level rules with a well-sequenced workflow that includes baseline and final validation plus explicit stop conditions. The two weaknesses are the absence of a concrete example or template (a sample refactor brief would make the guidance copy-paste ready) and the lack of an explicit error-recovery loop when validation fails mid-refactor.
Suggestions
Add an explicit feedback loop after the final validation step, e.g., 'If validation fails: revert the current stage (or fix and re-run `dev-smoke`) before proceeding' — this closes the workflow_clarity gap for destructive multi-file moves.
Include a compact example of the medium/large refactor brief (one filled-in template with evidence, do/defer/avoid ranking, and target shape) to lift actionability to copy-paste ready.
Name one concrete evidence-gathering command pattern for step 1 (e.g., how to capture imports/consumers) so 'current-code evidence' is executable rather than implied.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Lean and efficient throughout: every bullet is actionable guidance ('Subtract before adding', 'Separate moves/renames from logic changes', 'Validate with fresh command output') with zero explanation of concepts Claude already knows and no padding. All 39 lines earn their place, matching anchor 5. | 5 / 5 |
Actionability | Mostly concrete and executable: a precise size-classification rubric ('small = local/no public movement; medium = multi-file/extraction/boundary/export touch; large = package/cross-package/staged migration/broad consumers'), an itemized brief checklist, a staged sequence with a named tool (`dev-smoke`), and enumerated validation steps. Not 5: there is no worked example or template (e.g., a sample refactor brief or evidence-gathering command), and some directives remain abstract ('Check reader load', 'Prefer existing conventions'); not 3: the guidance is specific and directly followable, not pseudocode-level. | 4 / 5 |
Workflow Clarity | A clear 13-step sequence with explicit validation checkpoints — a pre-edit baseline ('run `dev-smoke` on affected flows; keep the script until the last stage') and a final validation step ('tests, compile/typecheck, lint, build, `dev-smoke` rerun matching the baseline, diff review') plus a Stop section of pause conditions. Not 5: there is no explicit error-recovery loop ('if validation fails, fix and re-validate / revert the stage'); not 3: validation is explicit at both start and end, so the missing-feedback-loop cap does not apply. | 4 / 5 |
Progressive Disclosure | The skill is a single SKILL.md under 50 lines with no bundle files and no content that belongs in a separate reference file; sections (Rules, Workflow, Stop) are well-organized and easy to navigate. The under-50-lines simple-skill exception applies, so well-organized sections alone merit 5; cross-references to sibling skills (`dev-simplify`, `dev-smoke`) are clearly signaled, not buried. | 5 / 5 |
Total | 18 / 20 Passed |