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.
A dense, expert-level instruction skill with strong actionability (exact commands, env vars, formats, and a lint-and-save finishing step) and a clearly ordered workflow with real verification checkpoints. Its weaknesses are repetition of the same guidance across sections, missing helper usage examples, no error-recovery paths, and a referenced kernel.py that is not present in the bundle.
Suggestions
State the kernel.py helper signatures (or one example call each) once — e.g. `search_openalex(query) -> records` — instead of repeating the bare helper-name list in three separate sections.
Merge the three overlapping prose-quality sections ("Synthesis is comparison", "Making the prose carry its weight", "Write prose, not a bulleted bibliography") into one, keeping the strongest examples from each.
Add brief failure-handling guidance — what to do when a DOI fails verification, when OPENALEX_API_KEY is absent, or when a sweep returns nothing — and ensure kernel.py ships with the bundle so the Setup reference resolves.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body assumes Claude's competence — no explanations of what a DOI or literature review is — but repeats itself: the kernel.py helper list appears three times ("verify_dois, crossref_lookup, search_openalex, expand_citations, extract_dois, style_pass" in Setup, again in the citation-format section, and again in Style pass), and the prose-not-bullets principle is restated across "Synthesis is comparison", "Making the prose carry its weight", and "Write prose, not a bulleted bibliography". Not 2: the padding is repetition of genuinely useful craft guidance, not explanation of known concepts; not 4 because a tightening pass would remove several redundant restatements. | 3 / 5 |
Actionability | Concrete, executable guidance throughout: the exact `exec(open("<this skill's directory>/kernel.py").read())` load line, named env vars (`OPENALEX_API_KEY`, `HOST_USER_EMAIL`) with the signup URL, named helper functions, the exact citation markdown format `[Author Year](https://doi.org/10.xxxx/xxxxxx)` with the `%28`/`%29` URL-encoding rule, and the one-shot `style_pass(draft)` procedure. Not 5: no helper signatures or a single example call (e.g. what `search_openalex` takes or returns), so first use requires inspecting kernel.py. | 4 / 5 |
Workflow Clarity | Sections are ordered as a real workflow — load helpers → read the request type → retrieval sweep → backward/forward citation expansion via `expand_citations(doi)` → retraction check → synthesis → style pass → save — with verification checkpoints ("Verification is something that happens in your tool trace", the update-to retraction check, and the explicit style-pass-then-save step). Not 5: no error-recovery guidance (failed DOI verification, missing OPENALEX_API_KEY, empty search results), so feedback loops are absent even though the sequence and checkpoints are clear. | 4 / 5 |
Progressive Disclosure | The body has clear, well-named sections and exactly one external reference (`kernel.py`), which is clearly signaled in Setup. However, the bundle contains no kernel.py (and no references/, scripts/, or assets/ directories), so the skill's single referenced file cannot be verified to exist, and helper API details are inlined in the body rather than disclosed from a reference. Not 4: a referenced-but-absent core file is more than a minor organization gap for an agent following the skill. | 3 / 5 |
Total | 14 / 20 Passed |