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 tight, executable skill body: commands are accurate against the bundled script, the output and citation contract is explicit, and structure is clean. The main deductions are time-sensitive version/roadmap notes and one documented flag (--snippet-len) the script does not actually honor.
Suggestions
Move the version/roadmap lines ('Phase 3.3.0', 'arrives 3.3.2', '3.3.1') out of SKILL.md into a changelog — time-sensitive info penalizes conciseness and will go stale.
Remove or actually implement '--snippet-len': query.js parses it but cmdSearch never reads it, so the documented tuning knob silently does nothing (also add '[--json]' to the related and show usage lines, which the script supports).
Drop the padding sentence 'Helps Claude recall existing knowledge instead of redoing research.' — the SessionStart example already shows the value.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumes competence ('Lower (more negative) rank = better BM25 match' is genuinely non-obvious), but the 'Limits (Phase 3.3.0)' section carries time-sensitive version/roadmap info ('Vector search arrives 3.3.2', 'MMR diversity arrives... in 3.3.1') outside any deprecated/old-patterns section, and 'Helps Claude recall existing knowledge instead of redoing research' is padding. | 4 / 5 |
Actionability | Commands are concrete and copy-paste ready ('node $SKILL_ROOT/scripts/query.js search "<query>" [--wiki <slug>] [--limit 10] [--json]') and match the actual script, but the Limits section documents '--snippet-len' which query.js parses but never reads (a no-op), and '[--json]' is omitted from the related/show usage lines even though the script supports it. | 4 / 5 |
Workflow Clarity | This is a simple single-purpose skill and the single action is unambiguous: the command syntax, output interpretation (JSON hit shape, rank semantics), and the mandatory citation format '[wiki:<slug>] <title> — `<rel_path>`' with 'Do not paraphrase a hit without showing the source' fully specify what to do; no destructive or batch operations are involved. | 5 / 5 |
Progressive Disclosure | A short, well-sectioned overview (When to use, Commands, Output, Citing back, SessionStart, Limits) whose only bundle dependency is scripts/query.js — a real file referenced one level deep via $SKILL_ROOT — with nothing inlined that belongs in a separate file. | 5 / 5 |
Total | 18 / 20 Passed |