Content
62%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.
The refactoring workflow itself is a model of clarity: six phases with mandatory validation checkpoints, failure recovery, baseline capture, and abort conditions. However, the skill is severely bloated by a repetitive harness-compatibility preamble and two full embedded documents inlined into a single file with no progressive disclosure, and the agent examples require nontrivial translation to be executable.
Suggestions
Move the Codex/OpenCode tool-compatibility table and the Team Mode Protocol into separate reference files (e.g., references/harness-compatibility.md, references/team-mode.md) linked from a short overview, cutting the main body to a lean phase guide.
Deduplicate the routing rules: state "If a code block below conflicts with this section, this section wins" once and consolidate the multi_agent_v1/v2 guidance into a single compact table instead of repeated prose paragraphs.
Rewrite the Phase 1/3/4 agent examples directly in the target harness's tool syntax (or a single canonical form) so they are executable without the reader mentally applying the translation table.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The ~780-line body is noticeably verbose: "If a code block below conflicts with this section, this section wins" is repeated three times, the Codex routing paragraphs restate V1/V2 rules across multiple dense blocks, and the template ends with motivational padding ("Remember: Refactoring without tests is reckless..."). It avoids explaining basic concepts Claude already knows, so it sits at anchor 2 rather than 1. | 2 / 5 |
Actionability | Concrete executable commands appear throughout: `python3 scripts/ast_grep_helper.py search 'function $NAME($$$) { $$$ }' src/ --lang ts`, `sg --pattern '[old_pattern]' --rewrite '[new_pattern]' --lang ts src/`, `tsc --noEmit`, LSP call signatures, and git commit templates. Minor gaps remain: agent examples use OpenCode-only tools that must be mentally translated per the preamble, and the ast-grep helper script lives in another skill's directory (honestly flagged as "this skill ships no scripts/"), matching anchor 4 rather than fully copy-paste-ready 5. | 4 / 5 |
Workflow Clarity | Phases 0-6 are explicitly sequenced with per-phase todos and mandatory post-step verification ("1. lsp_diagnostics → zero new errors / 2. Run test command → all pass / 3. Type check → clean"), a failure-recovery protocol (STOP → REVERT → DIAGNOSE → OPTIONS), a coverage-based verification strategy table, pre-change baseline capture, abort conditions, and commit checkpoints. Explicit validation with feedback loops and checklists matches anchor 5; anchor 4's "most checkpoints" understates the completeness. | 5 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are all absent), so everything lives in one ~780-line SKILL.md, including two large embedded documents — the full REFACTOR_TEMPLATE and the REFACTOR_TEAM_MODE_ADDENDUM — that clearly belong in separate reference files. Internal section structure is good, matching anchor 3 ("content that should be separate is inline") rather than anchor 2's "minimal structure". | 3 / 5 |
Total | 14 / 20 Passed |