Content
63%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 well structured with executable CLI guidance and a well-documented fallback architecture that matches the shipped script. Its main flaws are a large tail of generic template boilerplate, a Python example whose keyword arguments don't match the actual function signatures, and an orphaned references/apis.md file that is never navigated to from SKILL.md.
Suggestions
Delete or heavily trim the generic boilerplate sections (When Not to Use, Required Inputs, Recommended Workflow, Output Contract, Validation and Safety Rules, Failure Handling) — they add ~50 lines of padding that Claude already knows.
Fix the Python example to match the real signatures (download_by_doi(doi, output), search_download(query, max_results, output)) so it is copy-paste ready, and replace the fabricated --help expected output with the actual usage text.
Link references/apis.md from SKILL.md (e.g., under Dependencies or Implementation Details) and move the inline API host details there instead of duplicating them.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The core sections (When to Use, Example Usage, Implementation Details) are lean and specific, but roughly 50 of 180 lines are generic template boilerplate ("When Not to Use", "Required Inputs", "Recommended Workflow", "Output Contract", "Validation and Safety Rules", "Failure Handling") that restates what Claude already knows. Mostly efficient, but the padding is more than trimmable trivia, keeping it out of anchor 2's 'noticeably verbose' and below anchor 4. | 3 / 5 |
Actionability | CLI examples use flags that actually exist in scripts/download.py (--doi, --arxiv, --search, --max-results, --output) and the documented functions (download_by_doi, download_by_arxiv, search_download) exist in the script. Not a 5: the Python example passes output_dir= while the real signatures use output=, so it is not copy-paste ready, and the Quick Validation expected output does not match the script's actual --help behavior. | 4 / 5 |
Workflow Clarity | A clear source-priority fallback chain (Semantic Scholar → OpenAlex → Unpaywall → arXiv → PubMed → Crossref) with explicit error-handling expectations (retry per max_retries, then fall back to the next source, then report failures) provides most checkpoints. Minor gaps: the validation section's expected output is fabricated rather than tied to a real check, and the 'Recommended Workflow' section is generic filler rather than skill-specific steps. | 4 / 5 |
Progressive Disclosure | scripts/download.py is clearly and repeatedly signaled, but the bundle's references/apis.md (API endpoints, rate limits, error codes) is never linked from SKILL.md, and its content is partially re-inlined in the Dependencies and Implementation Details sections. This matches the anchor for references present but not clearly signaled; better signaling would earn a 4. | 3 / 5 |
Total | 14 / 20 Passed |