Content
71%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 highly actionable, well-structured CLI reference with executable examples for every command, real-world workflows, and thoughtful mistake-proofing (assembly fallback, truncation handling, HTTP 500 recovery). Its weaknesses are systematic redundancy — the same warnings repeated across Core Rules, callouts, and Common Mistakes — and bundle references (api-notes.md, citation.bib) that exist on disk but are never signaled from SKILL.md, leaving them effectively unreachable.
Suggestions
Consolidate repeated warnings: state each caution (search-region vs. resolve-variant, HGVS quoting, X/Y numeric chromosomes, --full payload size, assembly fallback) once in its most relevant location and have the Common Mistakes section reference rather than restate them.
Add a short 'References' section pointing to references/api-notes.md (NCBI endpoint details) and references/citation.bib (how to cite dbSNP) so the bundle files are discoverable from SKILL.md.
Add explicit validation steps to the Typical Workflows (e.g., 'verify the rsids array is non-empty before calling get-variant; if empty, check the assembly and ref allele per the troubleshooting section') to close the feedback loop.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly dense, skill-specific operational detail (assembly accessions, X=23/Y=24 conventions, retmax ceilings), but the same cautions are systematically repeated: the search-region warning appears in Core Rules, the CAUTION callout, and Common Mistakes; HGVS quoting and the X/Y chromosome rule each appear three times; the API-key/credentials instructions and --full warning are each stated twice. This goes beyond "minor instances that could be trimmed" (anchor 4), fitting anchor 3's "could be tightened". | 3 / 5 |
Actionability | Every subcommand has copy-paste-ready invocations with real example values (`uv run scripts/dbsnp_cli.py resolve-variant 8 19962213 C T --output /tmp/resolve.json`), explicit argument lists with defaults, expected output JSON shapes, and worked two-step workflows covering the common cases. Not 4 because there are no gaps — even edge conventions (numeric X/Y chromosomes, quoting HGVS) are given as executable specifics. | 5 / 5 |
Workflow Clarity | Multi-step workflows (resolve → get-variant, HGVS → rsID → coordinates) are clearly sequenced, and error recovery is addressed via the HTTP 500 troubleshooting section ("DO NOT RETRY... switch assembly") and the search-region truncated/note feedback. Not 5 because the workflow steps themselves lack explicit validation checkpoints (e.g., "check rsids is non-empty before running get-variant"); not 3 because checkpoints and recovery paths are largely present, just implicit in the workflows. | 4 / 5 |
Progressive Disclosure | The body is well-structured (prerequisites, command selection guide, per-command sections, workflows, troubleshooting), and the wrapper script is consistently referenced, but the bundle's references/api-notes.md (endpoint/API implementation details) and references/citation.bib are never mentioned anywhere in SKILL.md — verified by grep — so those files are undiscoverable. This matches anchor 3: "references present but not clearly signaled", rather than 2, since the body itself has strong organization and nothing that belongs in a separate file is inlined. | 3 / 5 |
Total | 15 / 20 Passed |