Content
82%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 well-crafted, highly actionable skill body with executable commands throughout, clear workflow sequencing, and proper use of bundle files for detail. The main improvement opportunities are deduplicating the repeated rate-limit warnings and the endpoint list, and adding an explicit verification step before exhaustive downloads.
Suggestions
Consolidate the rate-limit/API-key guidance into one place: the warning is repeated nearly verbatim in the prerequisites, the Rate Limiting bullet, and the Warning blockquote.
Replace the inline 28-endpoint listing under 'Available Endpoints' with a pointer to references/api_endpoints.md, which already documents the full list, to remove duplication.
Add an explicit verification checkpoint in the Workflow before exhaustive downloads (e.g., check the reported total_matching from a search before invoking download --all_results).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is efficient and assumes Claude's competence (no explanation of what the FDA or an API is), but the rate-limit warning is repeated three times ("Always set an API key before running multi-query workflows" appears in both the Rate Limiting bullet and the Warning blockquote, plus again in the prerequisites) and the Recipes section restates the description's full category enumeration verbatim. These are minor trimmable instances matching the 4 anchor rather than the fully lean 5 anchor. | 4 / 5 |
Actionability | Every subcommand (search, count, download) has a complete, copy-paste-ready `uv run scripts/openfda_query.py` invocation with all options documented, plus concrete executable examples for the key gotchas (quoting hyphenated NDCs, `.exact` matching with a fallback strategy). This fully matches the 5 anchor's 'copy-paste ready commands covering common cases'. | 5 / 5 |
Workflow Clarity | The Workflow section gives a clear 5-step sequence, and the content includes genuine error-recovery feedback loops (retry without `.exact` if 0 results; fall back from drug/ndc to drug/label for discontinued products). It falls short of the 5 anchor because the batch `download` path lacks an explicit verification checkpoint (e.g., checking `total_matching` before an exhaustive `--all_results` pull), leaving a minor validation gap consistent with the 4 anchor. | 4 / 5 |
Progressive Disclosure | SKILL.md is a well-organized overview with clearly signaled, one-level-deep references to references/api_endpoints.md and references/recipes.md (both verified to exist with no nested references), and bulk API detail is appropriately split out. Minor gaps keep it below the 5 anchor: the full 28-endpoint list is duplicated inline in the body, and references/citation.bib is present in the bundle but never referenced or explained. | 4 / 5 |
Total | 17 / 20 Passed |