Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Security

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 onecite

About 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 .bib file, 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 --json first 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 --json only 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

  1. Read the user's source reference material and preserve original text for traceability.
  2. Put one reference per blank-separated block in references.txt, or use the user's existing .bib file directly.
  3. Run onecite process ... --quiet to generate BibTeX.
  4. Run onecite process ... --json --fail-on-unresolved when a script needs a strict machine-readable gate.
  5. Run onecite benchmark --json before reporting regression-check results.
  6. Run onecite doctor --json before reporting that the local installation has the expected automation or CI resources.
  7. Inspect failed_entries, warnings, and duplicates in the process report, benchmark case failures, and doctor failed checks.
  8. Report unresolved entries explicitly instead of inventing replacements.

Interpreting Process Reports

  • warnings with type text_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 listed bib_key.
  • failed_entries[].reason tells 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; run onecite suggest and 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 suggest returns candidates for review, not verified citations. Check each suggestion's sources list: a status other than ok (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_score as no-confidence: do not present a top candidate as "the match" just because it ranks first. A year_conflict flag in score_breakdown means 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

  1. Start from the Roadmap section in README.md; choose one scoped Roadmap item or one explicit maintenance follow-up.
  2. Implement the change locally and keep unrelated edits out of the diff.
  3. Run local validation before release or handoff
Read the complete source ↗