Content
70%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 is an exceptionally well-sequenced, validation-rich workflow with genuinely copy-paste-ready commands — workflow clarity is near-textbook. Its two real weaknesses are verbosity from repeated qsv-lore passages (three restatements of the geocode distinction, duplicated tour/denominator rules) and a monolithic structure with no progressive disclosure, compounded by referencing an edit_dictionary.py script that is not present in the bundle.
Suggestions
Split deep reference material out of SKILL.md into one-level-deep files — e.g. references/dictionary-keys.md for the seven-key x-qsv table and the #4528 aggregation exceptions, and references/geojson-key-discovery.md for the ranking script — leaving SKILL.md a stage-by-stage overview that links to them.
State the geocode-enabled-build vs --geocode-flag distinction once (Stage 3a) and cut the restatements in the probe script's printed output and the Guardrails section; likewise state the x-qsv.tour version/language rules once instead of in both Stage 2.5 and Guardrails.
Ship edit_dictionary.py (as scripts/edit_dictionary.py) or remove the Stage 2.5 TUI stage — as bundled, the skill directs the user to run a script that does not exist beside SKILL.md, breaking the workflow at its reproducibility step.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Most of the ~880-line body is genuinely non-obvious qsv-specific knowledge (flag semantics, refusal modes, precedence rules) rather than concepts Claude already knows, so it is not anchor-2 padding — but several passages are padded or repeated: the geocode-enabled-build vs --geocode-flag distinction is explained three times (Stage 3a bullets, the probe script's printed output, Guardrails), the x-qsv.tour "version must stay the integer 1" rule appears in both Stage 2.5's table and Guardrails, and the denominator derivation story is told twice. This lands on anchor 3: mostly efficient but with unnecessary explanation that could be tightened — notably by deduplicating the geo-routing lore and trimming issue-number asides (#4401, #4528, #4547). | 3 / 5 |
Actionability | The guidance is overwhelmingly executable — exact qsv invocations with flags, parameter expansions like ${GEOJSON:+--geojson "$GEOJSON"}, complete copy-paste python heredocs for the dictionary coverage check and GeoJSON key ranking, and specified AskUserQuestion prompts with defaults. It falls short of 5 on real gaps: Stage 2.5's centerpiece `edit_dictionary.py` is described as living "beside this SKILL.md" but no such file exists in the bundle, and the Stage 2 endpoint resolution block leaves $MODEL unresolved until an interactive prompt Claude must fabricate structure for. | 4 / 5 |
Workflow Clarity | Stages 0–6 are explicitly ordered ("The order is load-bearing. Clean first, then describe, then draw.") with rationale for the ordering, and validation is woven throughout: Stage 0 preconditions, Stage 1's report-before-apply with a rows_affected-vs-nullcount sanity check, the Stage 2 dictionary coverage check gated before Stage 4 spend, Stage 5's verify-then-report with an explicit "Never claim success without checking", and Stage 6's capped two-loop refine→re-render→re-verify cycle. This matches the anchor-5 example's validate→fix→retry structure with feedback loops at every risky step. | 5 / 5 |
Progressive Disclosure | The stage-based headers make the document navigable, but it is a single ~880-line monolith with no reference files at all: the seven-row x-qsv hints table, the ~90-line GeoJSON feature-id ranking script, and the Stage 6 tour-refinement protocol are exactly the material the rubric expects split into one-level-deep referenced files. Worse, the one bundle file the body does reference — edit_dictionary.py "beside this SKILL.md" — is absent, so the reference is dangling in the bundle as shipped. Anchor 3 fits: real structure, but content that should be separate is inline and the sole script reference is not actually present. | 3 / 5 |
Total | 15 / 20 Passed |