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 highly actionable, well-structured skill body: executable commands for every subcommand, a clear workflow with an explicit user-confirmation gate, and clean one-level-deep references. The main costs are verbatim duplication between the Mindset and Anti-Patterns sections, a broken requirements.txt reference, and one self-contradictory DOI anti-pattern.
Suggestions
Collapse the duplication between "Mindset" items 1–3 and the first three "Anti-Patterns": keep the gotcha framing in one place and let the other section reference it, reclaiming ~20 lines of token budget.
Fix the "Dependencies: requirements.txt" link — the file is absent from the bundle; either add it or drop the entry and fold dependency info into setup-and-troubleshooting.md (which already cites it).
Rewrite the "NEVER use DOI and Semantic Scholar ID interchangeably" anti-pattern so its GOOD guidance matches the workflow's examples — currently "DOIs are accepted as-is in most contexts" contradicts the BAD example that mirrors the DOI usage shown in step 3.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is lean and assumes Claude's competence — no explanations of known concepts — but "IDs over titles", "Author IDs, not names", and the rate-limit note appear twice each (Mindset items 1–3 vs. Anti-Patterns 1–3), and the References section repeats the setup link from workflow step 2. Not 5 because that duplicated material costs tokens without adding information; not 3 because the padding is limited to restatement, not over-explanation. | 4 / 5 |
Actionability | Every subcommand has copy-paste-ready executable commands with realistic arguments ("./scripts/semantic-scholar-search.py paper --paper-id \"arXiv:2005.11401\""), plus a complete JSON-pipeline example for locating author IDs. Matches the fully-executable anchor covering the common cases; not 4 because there are no meaningful gaps. | 5 / 5 |
Workflow Clarity | A clear numbered sequence (choose subcommand → set up → run → find author ID → present and hand off) anchored by a selection table, with a user-confirmation gate ("NEVER triage automatically… confirm with the user") and a rate-limit guard. Not 5 because 429/error-recovery handling is delegated to the reference file rather than stated as an inline validation checkpoint; not 3 because checkpoints (confirmation gate, rate-limit warning) are present, and operations are read-only so no destructive-batch cap applies. | 4 / 5 |
Progressive Disclosure | The body is an appropriate overview with well-signaled, one-level-deep references ("See [setup-and-troubleshooting.md](references/setup-and-troubleshooting.md)") and a labeled References section. Not 5 because the "[requirements.txt](requirements.txt)" link in the References section points to a file that does not exist in the bundle (references/ holds only setup-and-troubleshooting.md), and the final Anti-Pattern on DOI vs. S2 IDs is internally muddled (its GOOD advice — "DOIs are accepted as-is" — contradicts its BAD example, which shows the same DOI usage pattern as workflow step 3). | 4 / 5 |
Total | 17 / 20 Passed |