Content
61%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 thorough, example-rich body that is highly actionable for common OpenAlex queries, supported by well-signaled reference files. It is held back by content redundancy between sections and the absence of explicit validation checkpoints in its batch and large-scale extraction workflows.
Suggestions
Consolidate the duplicated guidance (two-step pattern, per-page=200, batch_lookup, sampling) into a single 'Best Practices' section and reference it from the numbered capabilities instead of repeating each pattern twice.
Add explicit verification checkpoints to batch and large-scale workflows, e.g. after paginate_all confirm the returned count matches expected totals and after batch_lookup report any IDs that failed to resolve.
Move the Common Filter Patterns, Entity Types, and External IDs sections into references/api_guide.md, leaving SKILL.md as a concise overview that links out, to tighten token budget and improve progressive disclosure.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly concrete code with little concept over-explanation, but noticeable redundancy: the two-step pattern, per-page=200, batch_lookup, and sample usage each appear in both the numbered capabilities and the 'Critical Best Practices' section. | 3 / 5 |
Actionability | Abundant copy-paste-ready examples across the common cases, with only minor gaps such as the citation example bypassing the client via raw requests and the manual two-step relying on the private client._make_request method. | 4 / 5 |
Workflow Clarity | Sequences like the two-step entity lookup and troubleshooting error recovery are clear, but batch and large-scale operations (batch_lookup, paginate_all up to 10k+, sample_works >10k) lack explicit validation/verification checkpoints, capping this dimension at 3 per the batch-operation rule. | 3 / 5 |
Progressive Disclosure | Good structure with clearly signaled one-level-deep references to the real references/api_guide.md and references/common_queries.md (plus scripts), though a fair amount of filter-pattern and entity-type detail that could live in those references is inlined in SKILL.md. | 4 / 5 |
Total | 14 / 20 Passed |