Content
42%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 body has a sensible skeleton (trigger scoping, instructions, safety, output format) at a lean length, but it delivers almost no executable guidance — the concrete patterns are promised in a reference file that does not exist in the bundle, validation is a bare mention with no checkpoint, and the description is restated twice. It reads as a template shell rather than operational instructions.
Suggestions
Fix the dangling reference: 'resources/implementation-playbook.md' is referenced twice but no such file (or resources/ directory) exists in the bundle — either ship the playbook or remove the pointer.
Add one concrete anchor to the Instructions, e.g. a short example of a refactor step (extract duplicated logic into a named helper, run the affected test file, commit only if green) so the guidance is executable rather than aspirational.
Insert an explicit validation checkpoint into the workflow ('after each step, run the affected tests; if failing, revert before proceeding') and delete the duplicate persona/Context paragraphs that restate the description.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is short and mostly lean, but the opening paragraph repeats the frontmatter description verbatim, the 'Context' section restates it again ('The user needs help refactoring code to make it cleaner, more maintainable...'), and the 'Limitations' section is generic boilerplate ('Use this skill only when the task clearly matches the scope described above'). This is 'mostly efficient but includes some unnecessary explanation or could be tightened' rather than the minor-trim profile of anchor 4. | 3 / 5 |
Actionability | The Instructions are high-level directives — 'Identify high-impact refactor candidates and risks', 'Break work into small, testable steps', 'Apply changes with a focus on readability and stability' — with no concrete criteria, commands, patterns, or examples of what a refactor step looks like. The Output Format section names deliverables but not their content, matching 'minimal concrete guidance; high-level hints but missing the specific steps to execute'. Not 3 because there is no partially-complete executable detail anywhere — the concrete material is deferred to a reference file. | 2 / 5 |
Workflow Clarity | A rough sequence exists (identify candidates → break into steps → apply changes → 'Validate with tests and targeted regression checks'), so validation is named but as a terminal step with no checkpoints, no feedback loop for failures, and no guidance on when to stop or re-validate. This matches 'steps listed but validation gaps; sequence present but checkpoints missing or implicit'. Not 4 because there is no explicit validation checkpoint between steps and no error-recovery guidance for a workflow that modifies code in increments. | 3 / 5 |
Progressive Disclosure | The body is under 50 lines and cleanly sectioned (Use when / Do not use / Instructions / Safety / Output Format), and it defers detail via 'If detailed patterns are required, open resources/implementation-playbook.md' — but no resources/, references/, scripts/, or assets/ directories exist in the bundle, so this reference is a dangling path that would fail when followed. Scored against the actual bundle structure, structure is present but navigation breaks, matching anchor 3 rather than 4. | 3 / 5 |
Total | 11 / 20 Passed |