# 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. Use when this capability is needed. - Skill: `tomevault-io/onecite` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/onecite` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/onecite/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/onecite --- # 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: ```bash python -m pip install -e ".[dev]" ``` Use the repository's virtual environment when one exists: ```bash .venv/bin/python -m onecite.cli --help ``` ## Common Commands Process a plain-text reference file: ```bash onecite process references.txt -o references.bib --quiet ``` Process an existing BibTeX file: ```bash onecite process references.bib -o cleaned.bib --quiet ``` Process a direct identifier: ```bash onecite process "10.1038/nature14539" ``` List available fallback templates: ```bash onecite templates --json ``` Run the deterministic benchmark regression check: ```bash onecite benchmark --json ``` Check the local install, bundled resources, skill package, and offline benchmark gate: ```bash onecite doctor --json ``` Produce an automation-friendly validation envelope: ```bash onecite process references.txt --json --fail-on-unresolved ``` Stream newline-delimited events: ```bash onecite process references.txt --ndjson ``` Use live APIs for an upstream spot check: ```bash 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` in the process report, benchmark case failures, and doctor failed checks. 8. Report unresolved entries explicitly instead of inventing replacements. ## 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: ```bash python -m pytest flake8 onecite tests --statistics --count onecite benchmark --json onecite doctor --json python -m build --wheel ``` 4. Summarize the changed files, exact commands, pass/fail status, and any generated archive or wheel hashes. 5. Do not report local verification evidence until the local checks pass and references or failed checks are reported explicitly. ## Output Expectations For automation handoff, include: - the command used, - the output `.bib` path when one was written, - the benchmark status from `onecite benchmark --json`, - the doctor status from `onecite doctor --json`, - the `onecite process --json` status when strict validation was used, - unresolved entry IDs and error messages, - whether live APIs were used. ## Release and Review Checks For repository changes to OneCite itself, do not mark the Roadmap done unless these checks pass from the repository root: ```bash python -m pytest flake8 onecite tests onecite benchmark --json onecite doctor --json python -m build --wheel ``` For handoff, include the exact commands run, the pass/fail summary, the commit or diff reference, and any ZIP/wheel hash. Do not use live APIs for the default gate unless the user explicitly requests upstream-current behavior. ## Troubleshooting - If a `.bib` file is being treated as text, pass `--input-type bib`. - If plain text merges separate references, add blank lines between entries. - If Google Scholar is needed, install the optional dependency and pass `--google-scholar`; otherwise leave it off for deterministic runs. - If a benchmark must be reproducible in CI, do not pass `--live`. - If `onecite doctor --json` fails, fix the missing resource or failing benchmark before relying on package-level results. --- > Source: [HzaCode/OneCite](https://github.com/HzaCode/OneCite) — distributed by [TomeVault](https://tomevault.io).