{"id":"b9d31176-9b1b-4613-acb7-684c24b19acc","shortId":"jmh8Z4","kind":"skill","title":"verify-refs","tagline":"Audit-only verification of manuscript references against PubMed and CrossRef. Detects fabricated or mismatched citations and writes qc/reference_audit.json. Does not modify references/ or refs.bib.","description":"# Verify References (Audit-Only)\n\nYou help a medical researcher prevent reference hallucinations before submission.\nThis skill audits an existing manuscript or bibliography. It **does not write**\nto `references/` or `manuscript/_src/refs.bib`. It does not discover new\nliterature; use `/search-lit` for discovery and `/lit-sync` for bib management.\n\n## When to Use\n\n- Before journal submission, especially for `.docx` manuscripts inherited from\n  coauthors or external editors.\n- After AI-assisted drafting or revision introduced or modified references.\n- When a reviewer or collaborator flags a possibly fabricated citation.\n- Before `/sync-submission` freezes a journal package.\n\n## Inputs\n\n1. Manuscript or bibliography path: `.md`, `.docx`, `.bib`, `.txt`, or `.tsv`.\n2. Optional project root. Default: current working directory.\n3. Optional flags passed to the script:\n   - `--offline`: extract and classify references without API verification.\n   - `--timeout N`: HTTP timeout seconds.\n\n## Companion: pandoc citation key check\n\nFor markdown manuscripts using pandoc `[@bibkey]` citations, run the citation-key\nmatcher first to catch undefined/unused keys before this audit:\n\n```bash\npython \"${CLAUDE_SKILL_DIR}/../manage-refs/scripts/check_citation_keys.py\" \\\n  manuscript.md references.bib\n```\n\nThen run `verify_refs.py` against the .bib to validate each entry against\nPubMed/CrossRef. The two checks are complementary: `check_citation_keys.py`\ncatches mis-keyed cites; `verify_refs.py` catches fabricated metadata.\n\n## Deterministic Script\n\nRun the bundled script rather than verifying citations by memory:\n\n```bash\npython \"${CLAUDE_SKILL_DIR}/scripts/verify_refs.py\" manuscript/manuscript.md --project-root .\n```\n\nFor hooks or quick manual runs, use the wrapper:\n\n```bash\n\"${CLAUDE_SKILL_DIR}/scripts/verify_cli.sh\" manuscript/manuscript.md --offline\n```\n\n**Manual pre-submission strict run** (Phase 1A.5):\n\n```bash\n\"${CLAUDE_SKILL_DIR}/scripts/verify_cli.sh\" manuscript/index.qmd --strict\n```\n\n`--strict` forbids `--offline` and exits non-zero on any UNVERIFIED row.\nFull checkpoint protocol: `references/manual_checkpoint_guide.md`.\n\nThe script uses DOI, PMID, CrossRef, and PubMed E-utilities where available. If\nnetwork verification fails, it records `UNVERIFIED` rather than silently passing.\n\n## Output Contract (v1.1.1)\n\n| Artifact | Path | Purpose |\n|---|---|---|\n| Audit JSON | `qc/reference_audit.json` | Sole output — row-level status (OK/MISMATCH/UNVERIFIED/FABRICATED), counts, submission-safe flag, full records |\n\n**Removed in Phase 1A.2** (per `docs/artifact_contract.md`):\n- `references/verified_references.tsv` — record-level details now live inside `reference_audit.json` under `records[]`.\n- `references/library.bib` — never this skill's concern. `/search-lit` produces candidates; `/lit-sync` (via Better BibTeX) writes `manuscript/_src/refs.bib`.\n\nSole-writer enforcement: `scripts/validate_project_contract.py` will flag any `references/*` file written by this skill as drift.\n\n## Workflow\n\n1. Identify the input file and project root.\n2. Run `scripts/verify_refs.py`.\n3. Read `qc/reference_audit.json`.\n4. Report all `FABRICATED` and `MISMATCH` rows first (from `records[]`).\n5. If `UNVERIFIED` rows remain, list them as manual checks and do not call the\n   manuscript fully submission-safe.\n6. If the user needs a human-readable table, summarize from `records[]` in chat — do not write a TSV.\n\n## Quality Gates\n\n- Gate 1: stop submission if any row is `FABRICATED`.\n- Gate 2: require user confirmation before accepting `UNVERIFIED` references.\n- Gate 3: rerun after any reference edits.\n- Gate 4 (added 2026-04-26): first-author surname is cross-checked against\n  CrossRef/PubMed. A row whose DOI resolves but whose cited first author does\n  not match the authoritative source is downgraded to `MISMATCH` with\n  `note = \"first-author hallucination suspected\"`. This catches the common\n  LLM failure mode where a real DOI is paired with an invented author name.\n\n## First-Author Cross-Check (Detail)\n\nDriven by an actual incident: Paper 3 submitted to BMC Medical Education had\nref 8 cited as \"Ebrahimi S, et al.\" with the correct DOI for a Ballard et al.\ntask force whitepaper. Pre-patch verify-refs marked it OK because DOI resolved.\nPost-patch it is correctly flagged as `MISMATCH`.\n\n- Comparison is tolerant: case, diacritics, hyphen vs space, and name\n  particles (\"von\", \"van\", \"de\", ...) are normalized before matching.\n- If the cited surname cannot be parsed confidently (`first_author_guess`\n  empty), the check is skipped silently — no false MISMATCH from formatting\n  ambiguity.\n- Title-only PubMed search does not return an authoritative author and is\n  therefore excluded from this check.\n\n## What This Skill Does NOT Do\n\n- Does not generate new references from memory.\n- Does not replace missing citations with plausible alternatives without\n  `/search-lit` or user approval.\n- Does not sync Zotero collections; use `/lit-sync` after this audit.\n\n## Anti-Hallucination\n\n- Never fabricate titles, DOIs, PMIDs, author lists, journal names, years,\n  volumes, or pages.\n- Every OK row must be backed by DOI, PMID, CrossRef, or PubMed title evidence.\n- If evidence is unavailable, mark `UNVERIFIED` and keep it visible.","tags":["verify","refs","medsci","skills","aperivue","agent-skills","biostatistics","claude-code","claude-skills","clinical-research","diagnostic-accuracy","irb-protocol"],"capabilities":["skill","source-aperivue","skill-verify-refs","topic-agent-skills","topic-biostatistics","topic-claude-code","topic-claude-skills","topic-clinical-research","topic-diagnostic-accuracy","topic-irb-protocol","topic-literature-review","topic-manuscript","topic-medical-ai","topic-medical-research","topic-meta-analysis"],"categories":["medsci-skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/Aperivue/medsci-skills/verify-refs","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add Aperivue/medsci-skills","source_repo":"https://github.com/Aperivue/medsci-skills","install_from":"skills.sh"}},"qualityScore":"0.499","qualityRationale":"deterministic score 0.50 from registry signals: · indexed on github topic:agent-skills · 98 github stars · SKILL.md body (5,261 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:56:31.976Z","embedding":null,"createdAt":"2026-05-13T12:57:46.948Z","updatedAt":"2026-05-18T18:56:31.976Z","lastSeenAt":"2026-05-18T18:56:31.976Z","tsv":"'-04':479 '-26':480 '/../manage-refs/scripts/check_citation_keys.py':189 '/lit-sync':71,361,688 '/scripts/verify_cli.sh':254,269 '/scripts/verify_refs.py':236 '/search-lit':67,358,678 '/sync-submission':113 '1':119,384,451 '1a.2':338 '1a.5':264 '2':130,392,460 '2026':478 '3':138,395,469,549 '4':398,476 '5':408 '6':428 '8':557 'accept':465 'actual':546 'ad':477 'ai':93 'ai-assist':92 'al':563,572 'altern':676 'ambigu':637 'anti':693 'anti-hallucin':692 'api':151 'approv':681 'artifact':315 'assist':94 'audit':5,32,46,183,318,691 'audit-on':4,31 'author':483,500,515,534,538,624,648,700 'authorit':505,647 'avail':300 'back':713 'ballard':570 'bash':184,231,250,265 'better':363 'bib':73,126,197 'bibkey':168 'bibliographi':51,122 'bibtex':364 'bmc':552 'bundl':223 'call':421 'candid':360 'cannot':619 'case':600 'catch':178,210,216,519 'chat':442 'check':162,206,417,488,541,628,655 'check_citation_keys.py':209 'checkpoint':285 'citat':19,111,160,169,173,228,673 'citation-key':172 'cite':214,498,558,617 'classifi':148 'claud':186,233,251,266 'coauthor':87 'collabor':106 'collect':686 'common':521 'companion':158 'comparison':597 'complementari':208 'concern':357 'confid':622 'confirm':463 'contract':313 'correct':566,593 'count':328 'cross':487,540 'cross-check':486,539 'crossref':14,293,717 'crossref/pubmed':490 'current':135 'de':610 'default':134 'detail':345,542 'detect':15 'determinist':219 'diacrit':601 'dir':188,235,253,268 'directori':137 'discov':63 'discoveri':69 'docs/artifact_contract.md':340 'docx':83,125 'doi':291,494,528,567,586,698,715 'downgrad':508 'draft':95 'drift':382 'driven':543 'e':297 'e-util':296 'ebrahimi':560 'edit':474 'editor':90 'educ':554 'empti':626 'enforc':370 'entri':201 'especi':81 'et':562,571 'everi':708 'evid':721,723 'exclud':652 'exist':48 'exit':276 'extern':89 'extract':146 'fabric':16,110,217,401,458,696 'fail':304 'failur':523 'fals':633 'file':376,388 'first':176,405,482,499,514,537,623 'first-author':481,513,536 'flag':107,140,332,373,594 'forbid':273 'forc':574 'format':636 'freez':114 'full':284,333 'fulli':424 'gate':449,450,459,468,475 'generat':664 'guess':625 'hallucin':41,516,694 'help':35 'hook':242 'http':155 'human':435 'human-read':434 'hyphen':602 'identifi':385 'incid':547 'inherit':85 'input':118,387 'insid':348 'introduc':98 'invent':533 'journal':79,116,702 'json':319 'keep':729 'key':161,174,180,213 'level':325,344 'list':413,701 'literatur':65 'live':347 'llm':522 'manag':74 'manual':245,257,416 'manuscript':9,49,84,120,165,423 'manuscript.md':190 'manuscript/_src/refs.bib':59,366 'manuscript/index.qmd':270 'manuscript/manuscript.md':237,255 'mark':582,726 'markdown':164 'match':503,614 'matcher':175 'md':124 'medic':37,553 'memori':230,668 'metadata':218 'mis':212 'mis-key':211 'mismatch':18,403,510,596,634 'miss':672 'mode':524 'modifi':25,100 'must':711 'n':154 'name':535,606,703 'need':432 'network':302 'never':353,695 'new':64,665 'non':278 'non-zero':277 'normal':612 'note':512 'offlin':145,256,274 'ok':584,709 'ok/mismatch/unverified/fabricated':327 'option':131,139 'output':312,322 'packag':117 'page':707 'pair':530 'pandoc':159,167 'paper':548 'pars':621 'particl':607 'pass':141,311 'patch':578,590 'path':123,316 'per':339 'phase':263,337 'plausibl':675 'pmid':292,699,716 'possibl':109 'post':589 'post-patch':588 'pre':259,577 'pre-patch':576 'pre-submiss':258 'prevent':39 'produc':359 'project':132,239,390 'project-root':238 'protocol':286 'pubm':12,295,641,719 'pubmed/crossref':203 'purpos':317 'python':185,232 'qc/reference_audit.json':22,320,397 'qualiti':448 'quick':244 'rather':225,308 'read':396 'readabl':436 'real':527 'record':306,334,343,351,407,440 'record-level':342 'ref':3,556,581 'refer':10,26,30,40,57,101,149,375,467,473,666 'reference_audit.json':349 'references.bib':191 'references/library.bib':352 'references/manual_checkpoint_guide.md':287 'references/verified_references.tsv':341 'refs.bib':28 'remain':412 'remov':335 'replac':671 'report':399 'requir':461 'rerun':470 'research':38 'resolv':495,587 'return':645 'review':104 'revis':97 'root':133,240,391 'row':283,324,404,411,456,492,710 'row-level':323 'run':170,193,221,246,262,393 'safe':331,427 'script':144,220,224,289 'scripts/validate_project_contract.py':371 'scripts/verify_refs.py':394 'search':642 'second':157 'silent':310,631 'skill':45,187,234,252,267,355,380,658 'skill-verify-refs' 'skip':630 'sole':321,368 'sole-writ':367 'sourc':506 'source-aperivue' 'space':604 'status':326 'stop':452 'strict':261,271,272 'submiss':43,80,260,330,426,453 'submission-saf':329,425 'submit':550 'summar':438 'surnam':484,618 'suspect':517 'sync':684 'tabl':437 'task':573 'therefor':651 'timeout':153,156 'titl':639,697,720 'title-on':638 'toler':599 'topic-agent-skills' 'topic-biostatistics' 'topic-claude-code' 'topic-claude-skills' 'topic-clinical-research' 'topic-diagnostic-accuracy' 'topic-irb-protocol' 'topic-literature-review' 'topic-manuscript' 'topic-medical-ai' 'topic-medical-research' 'topic-meta-analysis' 'tsv':129,447 'two':205 'txt':127 'unavail':725 'undefined/unused':179 'unverifi':282,307,410,466,727 'use':66,77,166,247,290,687 'user':431,462,680 'util':298 'v1.1.1':314 'valid':199 'van':609 'verif':7,152,303 'verifi':2,29,227,580 'verify-ref':1,579 'verify_refs.py':194,215 'via':362 'visibl':731 'volum':705 'von':608 'vs':603 'whitepap':575 'whose':493,497 'without':150,677 'work':136 'workflow':383 'wrapper':249 'write':21,55,365,445 'writer':369 'written':377 'year':704 'zero':279 'zotero':685","prices":[{"id":"fe3e93b4-7fd1-4e2f-9b9d-dd8ab3f1571f","listingId":"b9d31176-9b1b-4613-acb7-684c24b19acc","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"Aperivue","category":"medsci-skills","install_from":"skills.sh"},"createdAt":"2026-05-13T12:57:46.948Z"}],"sources":[{"listingId":"b9d31176-9b1b-4613-acb7-684c24b19acc","source":"github","sourceId":"Aperivue/medsci-skills/verify-refs","sourceUrl":"https://github.com/Aperivue/medsci-skills/tree/main/skills/verify-refs","isPrimary":false,"firstSeenAt":"2026-05-13T12:57:46.948Z","lastSeenAt":"2026-05-18T18:56:31.976Z"}],"details":{"listingId":"b9d31176-9b1b-4613-acb7-684c24b19acc","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"Aperivue","slug":"verify-refs","github":{"repo":"Aperivue/medsci-skills","stars":98,"topics":["agent-skills","biostatistics","claude-code","claude-skills","clinical-research","diagnostic-accuracy","irb-protocol","literature-review","manuscript","medical-ai","medical-research","meta-analysis","physician-researcher","prisma","pubmed","radiology","reporting-guidelines","strobe","systematic-review","tripod-ai"],"license":"other","html_url":"https://github.com/Aperivue/medsci-skills","pushed_at":"2026-05-17T20:50:52Z","description":"Claude Code skills for medical research — literature search, reporting guidelines, statistical analysis, publication figures. Built by a physician-researcher, tested on real publications. MIT licensed.","skill_md_sha":"3e6eab075763d38065b5dcd9ce283c63e474bf6d","skill_md_path":"skills/verify-refs/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/Aperivue/medsci-skills/tree/main/skills/verify-refs"},"layout":"multi","source":"github","category":"medsci-skills","frontmatter":{"name":"verify-refs","description":"Audit-only verification of manuscript references against PubMed and CrossRef. Detects fabricated or mismatched citations and writes qc/reference_audit.json. Does not modify references/ or refs.bib."},"skills_sh_url":"https://skills.sh/Aperivue/medsci-skills/verify-refs"},"updatedAt":"2026-05-18T18:56:31.976Z"}}