Content
85%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 an unusually strong CLI skill document: fully executable examples for every subcommand, a command table, explicit error-recovery and batch-validation workflows, and a pitfalls section — with only minor repetition of sibling-skill routing. Its one real defect is structural: the only referenced file, REFERENCE.md, is not present in the bundle, leaving the deferred authentication/exit-code detail inaccessible.
Suggestions
Ship REFERENCE.md in the skill bundle (or inline its essential content — the exit-code table and key/timeout flags — into SKILL.md) so the link is not dangling.
Consolidate the sibling-skill routing guidance (scholar-sidekick-api / -mcp) into one location — the intro blockquote — and drop the repetitions in 'When to Use' and 'Pitfalls'.
Trim editorial phrases such as 'ergonomic subcommands mean you don't hand-build JSON request bodies' that add tone but no actionable information.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dense and assumes Claude's competence — a command table, copy-paste bash, flags, exit codes — with no padding explaining known concepts. Not 5: sibling-skill guidance ('prefer scholar-sidekick-api/-mcp') is repeated three times (intro blockquote, 'When to Use', 'Pitfalls') and a few phrases like 'ergonomic subcommands mean you don't hand-build JSON request bodies' could be trimmed. Not 3: these are minor instances, not several unnecessary explanations. | 4 / 5 |
Actionability | Every subcommand has executable, copy-paste-ready examples ('scholar format 10.1038/nphys1170 --style vancouver', 'scholar audit refs.bib --json | jq ".summary"', 'cat refs.ris | scholar audit'), plus install commands, exact flag lists, exit codes (0/1/2/3), and jq parsing patterns. Not 4: the examples cover all common cases across format, export, verify, and audit. | 5 / 5 |
Workflow Clarity | The 'Error-recovery loop (verify)' is an explicit numbered sequence with validation checkpoints and a feedback loop (check exit code → re-run with --json → classify real mismatch vs network/usage error → report exactly, never invent a verdict), and batch operations get --fail-on-issues / --fail-on-mismatch plus a final Verification section. Not 4: validation and error-recovery loops are explicit, not just implied. | 5 / 5 |
Progressive Disclosure | The body defers auth keys, --base-url/--timeout, and the full exit-code table to '[REFERENCE.md](REFERENCE.md)' — clearly signaled and one level deep — but no bundle files exist and REFERENCE.md is missing, so the deferred detail is unreachable. Not 4: the skill's single external reference is dangling, a real navigation failure rather than a minor organization gap. Not 2: the inline body itself is well-sectioned and appropriately sized, not monolithic or burying its references. | 3 / 5 |
Total | 17 / 20 Passed |