| name | crossref-lookup |
| description | Query Crossref for DOI validation, title matching, citation metadata, and bibliography audits. Use when resolving references or cleaning citation records. |
Crossref Lookup
Use this skill for citation metadata work backed by the Crossref REST API.
Instructions
- Prefer this skill when the user needs DOI validation, title search, citation metadata, or bibliography auditing.
- Use the bundled CLI:
- In this repository:
skills/crossref-lookup/scripts/lookup
- After installation:
~/.agents/skills/crossref-lookup/scripts/lookup
- Choose the narrowest mode that matches the request:
--doi for validating or enriching one DOI--title for title-to-DOI discovery--validate-file for one DOI per line--audit-bibliography for a bibliography file such as .bib or plain text
- Normalize DOI strings before interpreting failures.
- Acceptable raw forms include
10.xxxx/..., doi:10.xxxx/..., and https://doi.org/10.xxxx/...
- If the user has a contact email for polite-pool requests, pass it with
--email.
- Treat Crossref as citation metadata, not full text.
- If exact abstract-page wording, final pagination, or publisher formatting matters, verify the shortlisted record on the publisher or DOI landing page.
- When title search returns multiple plausible records, keep the ambiguity explicit instead of selecting a match silently.
- Use
--strict for audits that must fail on malformed, missing, or unresolved
records. Exit code 2 denotes a transient service/network failure; exit code 1
denotes invalid, missing, or other audit failures.
Quick Reference
| Task | Action |
|---|
| Validate DOI | skills/crossref-lookup/scripts/lookup --doi 10.1038/nature12373 |
| Search by title | skills/crossref-lookup/scripts/lookup --title "CRISPR-Cas9 genome editing" |
| Validate a DOI list | skills/crossref-lookup/scripts/lookup --validate-file dois.txt |
| Audit bibliography | skills/crossref-lookup/scripts/lookup --audit-bibliography refs.bib |
| Citation style | `--style apa |
| Write to file | --output crossref-report.txt |
| Polite-pool email | --email you@example.org |
| Strict audit | --strict returns nonzero for unresolved records |
Input Requirements
uv and network access; the bundled PEP 723 script installs its pinned HTTP dependency- One of:
- a DOI via
--doi
- a title via
--title
- a file path for
--validate-file
- a bibliography file path for
--audit-bibliography
- Optional:
--style for formatted citation output--output for saving the report--email for the Crossref user agent
Output
- DOI validation status and normalized DOI when
--doi is used
- title, journal, year, and formatted citation when metadata is found
- ranked title-search candidates for
--title
- summary counts that distinguish invalid DOI syntax, Crossref 404 records,
transient 429/5xx/network failures, and other HTTP errors
- optional output file if
--output is set
Quality Gates
Examples
Example 1: Validate a DOI
skills/crossref-lookup/scripts/lookup --doi "10.1038/nature12373"
Example 2: Search by title
skills/crossref-lookup/scripts/lookup \
--title "CRISPR-Cas9 genome editing" \
--email you@example.org
Example 3: Audit a bibliography
skills/crossref-lookup/scripts/lookup \
--audit-bibliography refs.bib \
--output crossref-audit.txt
Troubleshooting
Issue: The DOI looks valid but Crossref says it is missing.
Solution: Normalize the DOI first and retry. If it still fails, report that Crossref did not return a record instead of assuming publisher error.
Issue: Title search returns multiple plausible matches.
Solution: Return the shortlist with DOI, journal, and year so the user can disambiguate.
Issue: Bibliography audit reports missing DOIs for many entries.
Solution: Treat that as a coverage gap, not proof that the citations are invalid. Crossref metadata may be incomplete for some records.
Related Skills
/polars-dovmed — full-text PMC Open Access search when the DOI is unknown/arxiv-search — source-native preprint search on arXiv/biorxiv-search — source-native preprint search on bioRxiv/scientific-impact-assessment — citation counts and journal impact
