Content
85%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 instruction skill: a tight five-step workflow with real executable tooling, explicit verification, and correct use of a bundled script for the mechanical work. The only weaknesses are mild — a safety rule repeated three times and a project-specific cargo command presented as the universal verification step.
Suggestions
State the 'never remove a FIXME before implementing it' rule once (keep the Critical rule callout) and drop the repetitions in the step-4 list and the Notes section; step 2's 'Important' block can be folded into the step intro.
Generalize the verification step: instead of hardcoding 'cargo insta test --accept', instruct the agent to run the project's standard test command (detecting it from the repo, e.g. cargo/npm/pytest) and keep cargo insta as the example for this codebase.
Add an explicit recovery loop to step 5: if the re-run of find-fixme.sh still reports FIXMEs, return to step 2 for the remaining items instead of ending.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumes Claude's competence (no explanation of what a FIXME is, no library tutorials), but the core rule is stated three times — "Remove each FIXME comment only after the work it describes has actually been implemented", the "Critical rule" callout, and "The job is not to clean up comments" in Notes — and step 2's "Important" block restates the step's own heading ('A FIXME may be multiline'). This fits the level-4 anchor (efficient, minor instances that could be trimmed) better than level 3, since the padding is reinforcement of rules rather than unnecessary explanation of known concepts, and better than level 5, which requires every token to earn its place. | 4 / 5 |
Actionability | Guidance is mostly executable: the copy-paste command "bash .forge/skills/resolve-fixme/scripts/find-fixme.sh [PATH]" (a real, complete bundled script), the documented output contract (2 lines before, 5 lines after, file:line), and concrete checklists of what to capture and how to group. It falls short of the level-5 anchor because "Run the project's standard verification step: cargo insta test --accept" hardcodes a Rust/insta-specific command as if universal — for non-Rust projects this step is not executable as written, a concrete gap the anchor ('specific examples cover the common cases') would not have. | 4 / 5 |
Workflow Clarity | A clearly sequenced five-step workflow (discover → expand → consolidate → implement → verify) with an explicit validation checkpoint: re-run the discovery script and "Confirm that no FIXME comments remain in the targeted scope", plus the ordering guard that FIXMEs are removed only after implementation. Because this is a batch operation with validation and an ordering rule for the destructive part (comment removal), the level-3 cap for missing validation does not apply; it matches the level-5 anchor (clear sequence, explicit validation steps, feedback loop via re-running the finder) rather than level 4, which allows minor validation gaps. | 5 / 5 |
Progressive Disclosure | Scored against the actual bundle: the single reference target (scripts/find-fixme.sh) is a real, complete, self-documenting executable, and the body correctly keeps its internals (rg/grep fallback, exclusions, context-line counts) in the script instead of inlining them. The SKILL.md body is a well-organized overview of the workflow with clear section headers and one-level-deep navigation, fitting the level-5 anchor (clear overview, well-signaled one-level-deep reference, content appropriately split) rather than level 4, which presumes minor organization gaps. | 5 / 5 |
Total | 18 / 20 Passed |