Content
67%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 concrete, well-sequenced CLI skill: copy-paste commands for every workflow step, explicit script-resolution error handling, and a documented result schema. Its weaknesses are redundancy (the positioning/comparison content is repeated across four sections, rate limits stated three times) and total dependence on an external fetcher script that is not bundled with the skill.
Suggestions
Consolidate the four comparison/positioning sections (Role & Positioning table, 'Use OpenAlex when you want', 'OpenAlex vs Other Sources', and the two 'When to use X over Y' lists) into a single table — this removes roughly 40 lines of duplicated routing guidance.
State rate limits once (e.g., in Key Rules) instead of three times across Prerequisites, Key Rules, and the comparison table.
Add a validation checkpoint in Step 3/4 for empty or error API responses (check result count, then fall back to /semantic-scholar or /arxiv as Key Rules already suggests), turning the fallback guidance into an explicit workflow step.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The OpenAlex-vs-alternatives comparison is repeated across four sections ("Role & Positioning" table, "Use OpenAlex when you want", "OpenAlex vs Other Sources", "When to use OpenAlex over S2" / "When to use S2 over OpenAlex"), and rate limits are stated three times (Prerequisites, Key Rules, comparison table). Not 2 — the majority of the body is lean, actionable command guidance; not 4 — the duplicated positioning content is more than minor trimming. | 3 / 5 |
Actionability | Concrete copy-paste bash commands cover setup verification, the script-resolution chain, filtered searches, and DOI/OpenAlex-ID work lookups, and Step 4 documents every returned JSON field. Not 5 — all commands depend on an external `openalex_fetch.py` that is not in the bundle, so nothing is runnable without prior setup; not 3 — the guidance shown is fully executable, not pseudocode. | 4 / 5 |
Workflow Clarity | Six clearly sequenced steps (parse args → locate script → execute → parse → present → follow-up) with an explicit Verify Setup checkpoint and a real error-recovery loop in the script-resolution block (explicit remediation messages + exit 1). Not 5 — there are no checkpoints for empty or failed API responses within Steps 3-4 (rate-limit fallback is only mentioned after the fact in Key Rules); not 3 — sequence and script-resolution validation are explicit and concrete. | 4 / 5 |
Progressive Disclosure | A single-file skill (~229 lines) with clear section headers, one clearly signaled one-level-deep reference (shared-references/integration-contract.md), and no bundle files to split. Not 5 — the comparison tables and override syntax reference material are inlined and could live in a separate file to keep SKILL.md leaner; not 3 — structure is good, references are clearly signaled, and navigation is easy. | 4 / 5 |
Total | 15 / 20 Passed |