onecite
Validate, clean, and audit academic references with OneCite from a local repository checkout. Use when a workflow needs deterministic citation verification, BibTeX cleanup, benchmark gating, or template discovery.
HzaCode · Static checks on file
Installation
Read the source and dependencies before running a command. Copying does not install or execute anything.
npx skills add HzaCode/OneCite --skill oneciteAbout this skill
name: onecite description: Validate, clean, and audit academic references with OneCite from a local repository checkout. Use when a workflow needs deterministic citation verification, BibTeX cleanup, benchmark gating, or template discovery.
OneCite
Use this skill to turn raw references, DOI lists, arXiv IDs, PMID/ISBN-like identifiers, GitHub URLs, Zenodo/DataCite DOIs, or existing BibTeX into verified BibTeX output through the OneCite pipeline.
When To Use
- A manuscript, README, paper, package, or dataset has references that need canonical metadata lookup.
- A citation list has been generated or edited and needs a deterministic API-layer check before being trusted.
- A repository needs reproducible citation regression checks.
- A user asks for a clean
.bibfile, reference audit, or template discovery.
Ground Rules
- Do not fabricate bibliographic fields. Missing metadata should stay missing or be reported as a failure.
- Treat formatting success as different from truth. OneCite checks metadata against academic APIs; it does not prove that a citation supports a claim.
- Keep raw references separated by blank lines when using plain text input.
- Run
onecite benchmark --jsonfirst for deterministic offline regression checks; it uses bundled fixtures and does not require network access. - Use
onecite process ...for citation metadata lookup; unless test fixtures or mocks are explicitly configured, process mode may contact upstream APIs. - Use
onecite benchmark --live --jsononly when the user explicitly wants current upstream source behavior. - OneCite performs deterministic source lookups and formatting at runtime.
Setup
From the repository root:
python -m pip install -e ".[dev]"
Use the repository's virtual environment when one exists:
.venv/bin/python -m onecite.cli --help
Common Commands
Process a plain-text reference file:
onecite process references.txt -o references.bib --quiet
Process an existing BibTeX file:
onecite process references.bib -o cleaned.bib --quiet
Process a direct identifier:
onecite process "10.1038/nature14539"
List available fallback templates:
onecite templates --json
Run the deterministic benchmark regression check:
onecite benchmark --json
Check the local install, bundled resources, skill package, and offline benchmark gate:
onecite doctor --json
Produce an automation-friendly validation envelope:
onecite process references.txt --json --fail-on-unresolved
Stream newline-delimited events:
onecite process references.txt --ndjson
Use live APIs for an upstream spot check:
onecite benchmark --live --json
Automation Workflow
- Read the user's source reference material and preserve original text for traceability.
- Put one reference per blank-separated block in
references.txt, or use the user's existing.bibfile directly. - Run
onecite process ... --quietto generate BibTeX. - Run
onecite process ... --json --fail-on-unresolvedwhen a script needs a strict machine-readable gate. - Run
onecite benchmark --jsonbefore reporting regression-check results. - Run
onecite doctor --jsonbefore reporting that the local installation has the expected automation or CI resources. - Inspect
failed_entries,warnings, andduplicatesin the process report, benchmark case failures, and doctor failed checks. - Report unresolved entries explicitly instead of inventing replacements.
Interpreting Process Reports
warningswith typetext_metadata_mismatch: the entry resolved from its DOI, but the surrounding input text appears to describe a different work — the classic hallucinated title+DOI pairing. Surface this to the user for review; do not silently accept the entry.duplicates: the same work appeared more than once in the batch (bare DOI, PMID, formatted citation). It was emitted once; cite the listedbib_key.failed_entries[].reasontells you the correct follow-up:doi_not_found— the DOI does not exist in CrossRef or DataCite; likely fabricated or mistyped. Do not retry unchanged; flag it.no_strong_identifier— ambiguous plain text; runonecite suggestand have the result reviewed. Never promote a candidate to verified output yourself.source_error— a source errored; retrying later may succeed.pmid_unresolved/isbn_unresolved— the lookup found no record (nonexistent identifier or source unavailable/rate-limited).
Using Suggest Safely
onecite suggestreturns candidates for review, not verified citations. Check each suggestion'ssourceslist: a status other thanok(and an entry status ending in_incomplete) means a scholarly index was rate-limited or errored and the correct match may be missing from the list entirely.- Treat a low
match_scoreas no-confidence: do not present a top candidate as "the match" just because it ranks first. Ayear_conflictflag inscore_breakdownmeans the candidate's year contradicts the year the query cites. - To turn a reviewed candidate into verified BibTeX, take its DOI and run
onecite process "<doi>"— never hand-assemble an entry from candidate fields.
Anti-Hallucination Evaluation
Run the labelled non-fabrication evaluation (offline, deterministic):
onecite benchmark --anti-hallucination --json
It reports the resolution rate on real identifiers, the non-fabrication rate on ambiguous/fabricated inputs, and the mismatch detection rate on real DOIs paired with a different paper's title.
Repository Validation Checks
- Start from the Roadmap section in
README.md; choose one scoped Roadmap item or one explicit maintenance follow-up. - Implement the change locally and keep unrelated edits out of the diff.
- Run local validation before release or handoff