Content
46%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 core documentation (usage examples, inputs, returned fields, dependencies) is concrete and accurate to the bundled script, but roughly half the body is generic template boilerplate that adds no CrossRef-specific value, and the Quick Validation section presents a fabricated expected output. The result is a padded, partly vague workflow despite a solid executable core.
Suggestions
Delete the generic template sections (When Not to Use, Required Inputs, Output Contract, Validation and Safety Rules, Deterministic Output Rules, Completion Checklist, and the duplicate Quick Validation) — they restate behavior any competent model already knows and double the file's token cost without adding CrossRef-specific guidance.
Replace the fabricated "Expected output format" under Quick Validation with the actual output of `python scripts/query_crossref.py --help` (argparse usage text), and add one real example of the script's output so users can verify results against the documented format.
Rewrite "Recommended Workflow" as concrete CrossRef-specific steps (e.g., 1. resolve/search via query_crossref.py, 2. inspect returned fields such as title/author/is-referenced-by-count, 3. explicitly note when funder or citation-count fields are absent from the record) instead of abstract platitudes.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The first half (Validation Shortcut, When to Use, Key Features, Dependencies, Example Usage, Implementation Details) is efficient, but roughly half the body — "When Not to Use", "Required Inputs", "Output Contract", "Validation and Safety Rules", "Deterministic Output Rules", "Completion Checklist" — is generic template padding ("Do not use this skill when the user asks for fabricated results", "Keep the output safe, reproducible, and within the documented scope") that restates what any competent model already knows, and "Quick Validation" duplicates "Validation Shortcut". This is noticeably verbose with several padded sections, matching anchor 2 rather than the mostly-efficient anchor 3. | 2 / 5 |
Actionability | The usage commands are copy-paste ready and match the real script's flags (verified: --doi, --query, --limit exist in scripts/query_crossref.py), but the "Quick Validation" expected output is fabricated — `--help` prints argparse usage, not "Result file: crossref_database_result.md" — and there is no sample of the script's actual output. Concrete guidance is present but incomplete with a key-detail miss, fitting anchor 3 rather than the mostly-executable anchor 4. | 3 / 5 |
Workflow Clarity | "Recommended Workflow" lists a 4-step sequence, but the steps are abstract platitudes ("Select the documented execution path", "Run a final validation pass") rather than CrossRef-specific operations, and validation checkpoints are implicit rather than concrete commands; "Failure Handling" gestures at recovery but provides no executable retry loop. Sequence present with implicit checkpoints matches anchor 3, not the clear-checkpoints anchor 4. | 3 / 5 |
Progressive Disclosure | The body is organized into clear sections, and its single bundle reference (scripts/query_crossref.py) is real, one level deep, and used consistently. Minor gaps keep it below the top anchor: scripts/validate_skill.py exists in the bundle but is never referenced, and the inline boilerplate is content that should be deleted rather than restructured into separate files. This fits "good structure; most content appropriately placed; minor organization gaps". | 4 / 5 |
Total | 12 / 20 Passed |