crossref-lookup

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

1. Prefer this skill when the user needs DOI validation, title search, citation metadata, or bibliography auditing.
2. Use the bundled CLI:
   • In this repository: skills/crossref-lookup/scripts/lookup
   • After installation: ~/.agents/skills/crossref-lookup/scripts/lookup
3. 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
4. Normalize DOI strings before interpreting failures.
   • Acceptable raw forms include 10.xxxx/..., doi:10.xxxx/..., and https://doi.org/10.xxxx/...
5. If the user has a contact email for polite-pool requests, pass it with --email.
6. 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.
7. When title search returns multiple plausible records, keep the ambiguity explicit instead of selecting a match silently.
8. 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 [e-mail]
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

• The lookup mode matches the user request
• DOI inputs are normalized before treating them as invalid
• Ambiguous title matches are presented as candidates rather than a silent single answer
• Citation formatting uses the requested style when style matters
• The final answer distinguishes Crossref metadata from publisher full text

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 [e-mail]

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