Content
46%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 core usage guidance is concrete and executable, but the body is padded with redundant sections and generic template boilerplate, references a nonexistent script, and never points to its own bundled reference file. Trimming the boilerplate and fixing bundle navigation would substantially improve it.
Suggestions
Fix the broken script reference: 'python scripts/test_skill.py' in Example Usage should point to the actual bundled script, scripts/validate_skill.py.
Cut the generic template sections ('Deterministic Output Rules', 'Validation and Safety Rules', 'Failure Handling', 'Completion Checklist', 'Required Inputs', 'Scope Reminder') that add no file-search-specific value, and merge 'Key Features' and 'Implementation Details' into the examples to remove triple repetition of the same rg commands.
Link references/quick-reference.md from the body (e.g., a 'Quick reference: See references/quick-reference.md' line) so the bundled reference is discoverable instead of duplicating its content inline.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is noticeably verbose: the same commands appear three times across 'Key Features', 'Example Usage', and 'Implementation Details', and 'Implementation Details' explains ripgrep flags ('-C N prints N lines of leading and trailing context', '--type restricts scanning') that Claude already knows. Roughly half the document ('Deterministic Output Rules', 'Validation and Safety Rules', 'Failure Handling', 'Completion Checklist', 'Scope Reminder', 'Output Contract') is generic boilerplate not specific to file searching. | 2 / 5 |
Actionability | The 'Example Usage' block gives concrete, executable, copy-paste-ready commands (rg --version, rg --files --glob "*.rs", rg "TODO|FIXME", rg -C 3 "fn main" --type rust) covering common cases. It falls short of 5 because the example invokes 'python scripts/test_skill.py', which does not exist in the bundle (the actual script is validate_skill.py), and several boilerplate sections offer only vague direction. | 4 / 5 |
Workflow Clarity | A pre-check sequence exists ('ensure ripgrep is installed' before running searches) and 'Recommended Workflow' lists four steps, but those steps are generic template language ('Produce the expected output using the documented file format, schema, or narrative structure') not tied to actual search commands. There are also validation contradictions: 'Quick Validation' states 'No local script validation step is required' while the example runs a self-check script, leaving checkpoints implicit and inconsistent. | 3 / 5 |
Progressive Disclosure | The bundle contains references/quick-reference.md and scripts/validate_skill.py, but the body never links the quick-reference (its command list is duplicated inline in 'Example Usage'/'Implementation Details'), and its only bundle pointer — scripts/test_skill.py — does not exist. Navigation from SKILL.md to the actual bundle files effectively fails, fitting the anchor where content that belongs in separate files is inlined and references are buried. | 2 / 5 |
Total | 11 / 20 Passed |