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 dense, highly actionable command guide with realistic examples and unusually good validation/error-recovery guidance for a lookup tool. Its main weakness is structure: it is a monolithic 440-line SKILL.md whose full command API reference should be split into a references/ bundle file, with SKILL.md kept as overview plus common patterns.
Suggestions
Move the per-command API reference (query/search/exists/anchors/list/refs/trace/graph/idl/state/effects/flow details, PR previews, and update) into a references/commands.md file, keeping SKILL.md as a concise overview plus the highest-frequency patterns and one-line pointers per command.
Split the 'Usage patterns for Gecko development' scenarios into their own reference file (or trim to the 3-4 most common), and have SKILL.md signal it explicitly so the Gecko workflow detail is loaded only when relevant.
Remove small redundancies: the duplicated `webspec-index query 'DOM#concept-tree'` example and the pseudo-syntax placeholder line `webspec-index state 'SPEC#anchor' | --coverage SPEC [...]` in the state section.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Nearly every token is tool-specific knowledge Claude cannot infer — real commands, flag semantics, and gotchas like "Roughly 60% of references are not calls" and may-semantics — with no explanations of concepts Claude already knows. Not 5: there are minor trims available, e.g. the duplicated example `webspec-index query 'DOM#concept-tree'` and the pseudo-syntax placeholder line in the state section. Not 3: no padded or unnecessary explanatory sections. | 4 / 5 |
Actionability | Every section is copy-paste-ready bash with realistic concrete arguments ('HTML#navigate', "RFC9000#section-22", 'HTML#*sandbox*', 'Window.navigation'), documented flags, and described outputs. Specific examples cover the common cases for each subcommand, matching the fully-executable score-5 anchor. | 5 / 5 |
Workflow Clarity | Scenario workflows sequence commands with comments, and validation checkpoints with error-recovery loops are explicit: "Read `Search was truncated` before trusting the result — raise `-l` or narrow the endpoints", "confirm an absence with `refs --direction incoming --kind step` before concluding a call does not exist", and `exists` exit-code validation before citing anchors. The tool involves no destructive or batch operations, so no cap applies. | 5 / 5 |
Progressive Disclosure | No bundle files exist (references/, scripts/, assets/ are absent) and all ~440 lines — including the full per-command API reference — are inlined in SKILL.md. Section headers give it some structure, but the command-reference bulk clearly belongs in a one-level-deep references/ file, matching the score-3 anchor (content that should be separate is inline) rather than 4 (most content appropriately placed). | 3 / 5 |
Total | 17 / 20 Passed |