---

name: ref-verify description: "Prevents citation hallucination in academic writing. Invoke when: finding papers to support a specific claim; verifying/checking/auditing existing citations or DOIs; confirming whether a paper actually says what the user claims it says ('is that what the paper says?', 'did they actually show X?'); adding a citation by describing a paper ('add a citation for the paper where X'); running a pre-submission reference sweep. Do NOT invoke for: formatting references in APA/IEEE style, general topic explanations, citation style questions, or prose editing. Selects Quick Screen (seconds per paper) or Full Audit (source-depth claim check) automatically."

ref-verify — Reference Hallucination Guard

The specific failure this skill prevents: LLMs describe paper content from recalled training data rather than from what the abstract actually says. A paper gets attributed findings it doesn't contain, or cited for claims that appear nowhere in the text. The fix is one rule applied consistently:

Every content statement about a paper must come from a live-fetched source — abstract for topline/headline claims, full text for mechanism/implementation/procedural claims — quoted or paraphrased verbatim. If you cannot fetch the required source, say so explicitly — never fill the gap with recalled description, and never let a topical abstract match stand in for a mechanism-level claim.

---

Mode Decision

Pick the mode before doing any work. The choice controls cost and depth.

User provides DOI(s) for sanity check?
  └─ ≤10 refs → Quick Screen all
  └─ >10 refs → Quick Screen all; Full Audit only MISMATCH/DEAD results

User says "find papers on X" or "cite papers supporting claim Y"?
  └─ Full Audit (searching from scratch requires content verification)

User says "verify/check my reference list" or pre-submission audit?
  └─ CLI available → Pre-submission sweep (below) first: check-bib, then check-file
  └─ ≤5 refs  → Full Audit all
  └─ >5 refs  → Quick Screen all first; Full Audit MISMATCH/DEAD + any ref
                 cited for a specific factual claim

User is writing inline and adds a single citation from memory?
  └─ Quick Screen minimum; Full Audit if citing for a specific claim

The expensive part is Full Audit (5-layer, source-depth evidence fetch). Quick Screen costs ~5s per paper. Only escalate to Full Audit when the task genuinely requires content verification.

---

Executable Engine

Use this as a skill-level workflow. Do not build or require MCP for this path. The CLI is an execution engine the skill can call from the terminal; the manual protocol remains the fallback and the source of truth for layers the CLI does not yet cover.

CLI Availability Check

The skill ships its own engine: npx skills add copies the src/ folder next to this SKILL.md. Before a DOI-backed check, resolve the engine once, in this order, and keep the first command that prints help:

1. Bundled with this skill (same version as this SKILL.md; no install, no network for setup):

   PYTHONPATH="$SKILL_DIR/src" python3 -m ref_verify.cli --help
   

   $SKILL_DIR is the absolute path of the folder that contains this SKILL.md (Claude Code shows it as the skill's base directory; npx skills add -g installs it under ~/.agents/skills/ref-verify). Never use a relative src path: the working directory is the user's project, not the skill folder. Requires Python 3.10 or newer.

2. Installed console script (pip install ref-verify or pipx install ref-verify):

   ref-verify --help
   

   npx skills add does not pip-install the Python CLI, so this is often absent.

3. From PyPI through uv:

   uvx --from 'ref-verify>=1.3.2' ref-verify --help
   

The commands below use the bundled form; with engine 2 or 3, replace PYTHONPATH="$SKILL_DIR/src" python3 -m ref_verify.cli with ref-verify (or the uvx form). An unavailable engine is not a verification result. If all three fail, follow the manual fallback protocol below. Do not pretend the CLI ran, and do not invent a result from memory.

CLI-first workflow

Use the CLI first when the user provides a DOI or asks whether a DOI-backed abstract supports a specific factual claim. Current CLI scope is CrossRef metadata verification plus DOI-bound abstract claim checks. Claim checks use CrossRef first, then DOI-bound OpenAlex, Semantic Scholar, and PubMed fallback when CrossRef has no abstract.

CrossRef metadata screen:

PYTHONPATH="$SKILL_DIR/src" python3 -m ref_verify.cli verify-doi <doi> \
  --title "<provided title>" \
  --first-author <provided-first-author-last-name> \
  --year <provided-year> \
  --json

verify-doi exits 0 only for PASS; WARN and REJECT return non-zero. Supplying only a DOI checks that CrossRef resolves but is not enough to pass metadata verification.

Route the result:

• PASS: report the metadata match, then continue Layer 4 DOI landing-page resolution and Layer 5 retraction checks when the selected mode requires them.
• WARN: report the missing or weak metadata, then continue manual fallback for the missing layers instead of silently accepting the reference. With DOI_NOT_IN_CROSSREF the DOI is registered outside CrossRef (arXiv, Zenodo, KISTI); verify title and authors at doi.org and never call the DOI dead.
• REJECT: stop using that citation as verified; report the mismatch and ask for a corrected DOI or citation unless the user explicitly wants alternatives.

Reference list check (BibTeX, RIS, or a plain-text/Markdown bibliography). Run this first when the user hands over a reference list, then check claims:

PYTHONPATH="$SKILL_DIR/src" python3 -m ref_verify.cli check-bib <references.bib|.ris|.txt|.md>

When the user wants something to read or share (an advisor, co-authors), add --report <name>.html (or .md): the HTML lists the items that need a look first and explains each verdict in plain words. Give the user the report path.

Route each result:

• PASS: the reference matches a CrossRef record (by its DOI, or found by search with REFERENCE_RESOLVED and a resolved_doi).
• WARN with REFERENCE_UNMATCHED (status: UNVERIFIED): CrossRef search found no matching record. Report it as unverified and run the manual Quick Screen on it; do not call it fabricated from this result alone.
• WARN with DOI_NOT_IN_CROSSREF (status: UNVERIFIED): the DOI is registered with another agency (arXiv/Zenodo via DataCite, KISTI, JaLC), so its metadata was not compared; confirm it at doi.org, never call it dead.
• Other WARN: metadata partly differs, the reference text was too thin to confirm, or (status: MISMATCH) a plain-text reference's DOI belongs to the paper named in reason; report the reason and check manually.
• REJECT: dead DOI (DOI_NOT_FOUND), retraction (PAPER_RETRACTED), or a DOI that points to a different paper. Stop using it as verified.

Single claim check against a DOI abstract:

PYTHONPATH="$SKILL_DIR/src" python3 -m ref_verify.cli check-claim <doi> --claim "<specific factual claim>" --json

--source crossref|openalex|semantic-scholar|pubmed forces one source (it bypasses CrossRef), for debugging a single source's failure.

Route the result:

• ACCEPT: quote the CLI evidence and continue any required manual DOI resolution, second-source existence, and retraction layers.
• WARN or PARTIAL: report what the selected abstract source did and did not support, then continue manual fallback when more layers are required.
• UNVERIFIABLE: no trusted DOI-bound abstract evidence was available from the attempted CLI sources. Continue the manual fallback chain below instead of treating the claim as rejected or supported.

CLI ACCEPT is abstract-level evidence only. It means every number in the claim, with its unit, sign, and direction, is supported by the same abstract sentence; one number the sentence does not support blocks ACCEPT even when another number matches. If the claim describes a mechanism, implementation, or procedure, do not promote that result to the Full Audit verdict; classify the claim in Layer 3 and obtain the required full-text evidence first.

For JSON output, use abstract_source, source_attempts, and error_code to decide the next step:

• CLAIM_SUPPORTED: explicit abstract support found.
• CLAIM_NOT_EXPLICIT: an abstract was available, but the claim was not explicitly supported.
• CLAIM_AMBIGUOUS: numeric evidence or context exists, but binding is ambiguous.
• NO_ABSTRACT: attempted DOI-bound sources did not provide abstract text.
• DOI_NOT_FOUND: neither CrossRef nor doi.org knows the DOI, or the selected source did not find a DOI-bound record.
• PAPER_RETRACTED: CrossRef lists a retraction notice for the DOI; the claim is rejected before any abstract is read.
• DOI_MISMATCH: the primary or explicitly selected DOI-bound record did not match the requested DOI.
• SOURCE_API_ERROR, SOURCE_TIMEOUT, SOURCE_RATE_LIMITED, SOURCE_UNSUPPORTED: source lookup failed, timed out, was rate-limited, or could not be used.
• REFERENCE_RESOLVED, REFERENCE_UNMATCHED (check-bib only): a reference without a DOI did or did not match a CrossRef record.
• DOI_NOT_IN_CROSSREF (verify-doi, check-claim, check-file, check-bib): the DOI exists at another registration agency (DataCite, KISTI, JaLC), so it is unverified rather than dead. check-claim still judges the claim when OpenAlex or Semantic Scholar has the abstract; otherwise confirm the work at doi.org.

The CLI does not replace Layer 4 DOI landing-page resolution or two-source existence checks, and it only catches retractions that CrossRef records as a retraction notice. Continue the manual protocol for those layers when the selected mode requires them.

Pre-submission sweep

Use the engine for both jobs. It queries CrossRef and doi.org for references and CrossRef, then OpenAlex, Semantic Scholar, and PubMed for abstracts, with a cache; do not hand-write curl calls for these.

1. References → check-bib. Save only the reference list (the References section, or the .bib); body paragraphs become spurious UNVERIFIED rows. The text output gives one verdict and reason per reference. --json is too large for one tool result: write it to a file (--json > refs-check.json) and read it in parts.
2. Numeric claims → check-file. Write claims.jsonl, one {"id", "doi", "claim"} per cited sentence with a number (DOI from the reference or check-bib's resolved DOI). Copy numbers, units, and direction words exactly as the manuscript has them (\SI{172.3}{\joule\per\mole} is 172.3 J/mol); never correct a claim while copying it. Run PYTHONPATH="$SKILL_DIR/src" python3 -m ref_verify.cli check-file claims.jsonl. The text output gives each claim's verdict and the abstract sentence it matched (Evidence).
3. Judge each claim from that sentence, never from memory or the label alone.
   • Different value, unit, or direction → the manuscript misstates the paper, even under ACCEPT; quote the sentence and give the correct value.
   • Same value, unit, and direction → quoted abstract support, not a problem (the label stays WARN in any verdict table).
   • Sentence about something else, or about only part of the claim → read the whole abstract (check-claim prints it under paper) before writing that the abstract does not state it.
4. Look up by hand only what the engine left undecided (REFERENCE_UNMATCHED, DOI_NOT_IN_CROSSREF, UNVERIFIABLE): Layer 1 sources and doi.org. For a citation without a title, search the author and journal plus the topic words of the sentence citing it; a record that fits but has another volume or page means the citation's volume or page is wrong. Mechanism claims s