Content
50%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 has a genuinely useful core — a complete runnable API example, concrete endpoint patterns, and domain-specific cautions (rate limits, evidence levels, phenoconversion) — but it is buried in duplicated boilerplate section pairs and ~10 generic template sections that carry no domain information. Structural fixes (deduplication, naming the reference file, removing fabricated output claims) would raise most dimensions substantially.
Suggestions
Delete the first set of template sections (lines 13-52: 'When to Use', 'Key Features', 'Dependencies', 'Example Usage', 'Implementation Details') and the generic filler sections ('Deterministic Output Rules', 'Output Contract', 'Failure Handling', 'Completion Checklist', 'Scope Reminder'); keep only the numbered, domain-specific sections 1-5 to roughly halve the token cost.
Replace the vague 'Reference material available in `references/`' with explicit links like 'Full endpoint documentation: See [references/api_reference.md](references/api_reference.md)' so the 756-line reference is clearly signaled and the inline endpoint list can shrink to the few most common patterns.
Rewrite 'Recommended Workflow' with concrete, executable checkpoints (e.g., verify the script runs with `python scripts/query_clinpgx.py --help`, then query a known pair like CYP2C19/clopidogrel and confirm JSON returns before running the user's actual query), and remove the '--help' expected-output block that does not reflect the script's real behavior.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is noticeably verbose with pervasive template padding: it contains two of each section ('When to Use' vs '1. When to Use', 'Key Features' vs '2. Key Features', 'Dependencies' vs '3. Dependencies', 'Example Usage' vs '4. Example Usage', 'Implementation Details' vs '5. Implementation Details'), where the first of each pair is contentless boilerplate ('Use this skill when the request matches its documented task boundary', 'Structured execution path designed to keep outputs consistent and reviewable'). Roughly ten further generic sections ('Deterministic Output Rules', 'Output Contract', 'Failure Handling', 'Completion Checklist', 'Scope Reminder') add no ClinPGx-specific information, and the dependencies statements contradict each other ('not explicitly version-pinned in this skill package' vs the pinned 'requests >=2.31.0'). It is not a 1 because a substantial core (the runnable Python example, endpoint patterns, rate limiting) genuinely earns its tokens. | 2 / 5 |
Actionability | The Python example is complete and copy-paste runnable with rate limiting and 429 backoff, and the endpoint patterns are concrete with example paths ('GET /gene/{symbol} (e.g., /gene/CYP2D6)', 'GET /variant/{rsid} (e.g., /variant/rs4244285)'). Minor gaps keep it at 4: the run plan tells the user to 'Edit the in-file CONFIG block' without establishing the script has one, the hardcoded 'cd "20260316/scientific-skills/..."' path is questionable, and the 'Quick Validation' section claims a '--help' invocation produces a result-file summary format it almost certainly does not. | 4 / 5 |
Workflow Clarity | Sequences exist ('Example run plan', 'Recommended Workflow': validate request, select execution path, produce output, run final validation) but they are generic and duplicated, with no concrete checkpoint commands — 'run a final validation pass for completeness, consistency, and safety' names no actual check. The only concrete verification is 'python scripts/query_clinpgx.py --help'. It reaches 3 rather than 2 because a real, ordered sequence for API querying is present and the operations are read-only, so no destructive-operation cap applies; it cannot reach 4 because checkpoints are implicit rather than executable steps. | 3 / 5 |
Progressive Disclosure | The bundle does contain references/api_reference.md (756 lines) and scripts/query_clinpgx.py, but the body never names or links the reference file — it only offers vague pointers ('Reference material available in `references/`', '`references/` contains supporting rules, prompts, or checklists') — while inlining a condensed API reference (endpoint list, rate limiting, evidence levels) that overlaps the dedicated reference file. This matches the anchor of references present but not clearly signaled with content that could live in the separate file inline; it is above 2 because real structure and one-level-deep bundle layout exist, but below 4 because the reference is not explicitly signaled or navigable from the body. | 3 / 5 |
Total | 12 / 20 Passed |