Content
78%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-structured, lean skill body with executable commands, explicit compile/verify safety gates, and exemplary one-level-deep progressive disclosure. Remaining weaknesses are redundant duplication between the Constraints and Workflow sections and a missing error-recovery loop for post-change verification failures.
Suggestions
Merge the compile/verify bullets in the Constraints section into Workflow steps 1 and 4 (or vice versa) to remove the duplicated instructions.
Add a verify-failure feedback loop, e.g. 'If mvn clean verify fails, fix the failing changes or revert them, then re-run verification before completing the task.'
Trim or drop the 'When to use this skill' section, which duplicates the frontmatter description triggers, and add one line of guidance on how to prioritize high-value refactoring candidates from the reference.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean — a bulleted feature list, constraint bullets, and a 4-step workflow with no explanation of concepts Claude already knows. However, the Constraints section repeats the compile/verify instructions already given in Workflow steps 1 and 4, and 'When to use this skill' duplicates the frontmatter triggers, so it is not fully tight. | 4 / 5 |
Actionability | Concrete, executable commands are given throughout ('./mvnw compile or mvn compile', './mvnw clean verify'), plus an exact file to read (references/141-java-refactoring-with-modern-features.md) and explicit edge-case protocols (stop and ask when scope is ambiguous). The gap is step 3, 'Refactor incrementally using appropriate language/library features', which delegates the actual how without summarizing any selection criteria. | 4 / 5 |
Workflow Clarity | The 4-step sequence is clear with explicit validation gates (compile before changes, 'stop immediately' on failure, full verify after), plus stop-and-ask checkpoints for ambiguity and missing tooling. It falls short of a 5 because there is no feedback loop for verify failures — no instruction to fix errors and re-run before finishing. | 4 / 5 |
Progressive Disclosure | SKILL.md is a concise overview that appropriately pushes all good/bad code examples into a single reference, which exists, is clearly signaled twice (workflow step 2 and a markdown 'Reference' link), and is one level deep — the 54KB reference has its own TOC and no nested .md references. | 5 / 5 |
Total | 17 / 20 Passed |