Content
90%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 content is an exemplary command reference: fully executable examples for all 8 commands, lean prose with zero filler, concrete workflow compositions, and a pitfalls section that captures real operational failure modes. Its only weaknesses are minor: verification exercises just 2 of 8 commands, the script path is given only in deployment form rather than relative to the skill bundle, and the intro claims "44 POI categories" while the nearby section (and the script's CATEGORY_TAGS) lists 46.
Suggestions
Fix the internal inconsistency: the intro says "44 POI categories" but the nearby section and scripts/maps_client.py both contain 46.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean throughout: every command gets an executable example with a one-line "Returns:" summary, there is no explanation of concepts Claude already knows (no "what is OSM" padding), and the 46-item category list is operational data (valid CLI values) rather than filler. Matches anchor 5 ("Lean and efficient; assumes Claude's competence; every token earns its place"); not 4 because no section requires trimming — even the Pitfalls and Verification sections carry unique, actionable information. | 5 / 5 |
Actionability | All 8 commands come with copy-paste-ready invocations via the defined `$MAPS` variable, realistic arguments ("Eiffel Tower", "Times Square"), flag examples (--limit, --radius, --mode, --category), and a Verification section with expected outputs. Matches anchor 5 ("Fully executable; copy-paste ready code or commands; specific examples cover the common cases"); not 4 because there are no gaps — output fields and modes are enumerated for every command. | 5 / 5 |
Workflow Clarity | Workflow Examples sequence multi-step cases (extract pin coordinates → nearby; area → bbox), the Telegram-pin section includes a feedback loop ("if missing or unclear, verify with web_search"), and Pitfalls covers error handling (Overpass mirror fallback, ambiguous zips). Not 5 because explicit verification covers only 2 of the 8 commands (search and nearby) — distance, directions, timezone, area, and bbox have no checkable expected output, a minor validation gap per anchor 4; not 3 because validation steps are present and sequences are coherent with checkpoints where it matters. | 4 / 5 |
Progressive Disclosure | The body is a well-sectioned overview (When to Use, Commands, Workflows, Pitfalls, Verification) with a single script bundle file whose path is referenced consistently, matching the actual bundle structure (scripts/maps_client.py, no nested references). Not 5 because the script is referenced only by its deployment path (~/.hermes/skills/maps/scripts/maps_client.py) rather than a bundle-relative path, and quick-reference material like the full category list and per-command flag details is inlined where a one-level-deep reference file would keep the overview tighter; not 3 because navigation is easy and nothing is buried or monolithic. | 4 / 5 |
Total | 18 / 20 Passed |