# Highlight Citations > Precisely highlight, in each reference PDF, the exact sentence that supports the specific claim it is cited for in a manuscript — and flag citations whose source paper does not actually support that claim. Use when the user asks to "标记引用"/"高亮参考文献"/"mark the cited passage", wants supporting quotes highlighted in downloaded reference PDFs, or asks to verify that citations in a manuscript actually say what they're cited for. - Skill: `hannah96z/highlight-citations` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add hannah96z/highlight-citations` - Raw SKILL.md: https://api.skillmd.com/api/skills/hannah96z/highlight-citations/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: Hannah96Z (https://skillmd.com/u/hannah96z) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/hannah96z/highlight-citations --- # Highlight Citations ## What this does Given a manuscript with numbered in-text citations (`[1]`, `[1–4]`, etc.) and a folder of the corresponding reference PDFs, this skill: 1. Finds, for each citation, the exact sentence in that PDF that supports the specific claim it's attached to in the manuscript — not just a keyword match, not the paper's own title. 2. Adds a real PDF highlight annotation on that exact sentence. 3. Flags citations where the source paper does **not** actually contain content supporting the claim (mismatched citation, not just a marking problem) and asks the user how to resolve it — remove, relocate to a claim it does support, or leave for the user to decide. Never silently force a highlight onto unrelated content just to have *something* marked. 4. When a citation is removed, renumbers everything that follows: in-text citation numbers (by order of first appearance, Vancouver style), the reference list, and the numeric prefixes on the PDF filenames — then re-verifies the whole set is internally consistent. ## Why "highlight the title" is not acceptable The most common failure mode (encountered repeatedly in practice) is a highlight that lands on the paper's own title or a repeated running header instead of a real supporting sentence. This is worse than useless — it looks like the citation was checked when it wasn't, and it gives the user (or their advisor) zero information about *why* the paper is cited. Every highlight this skill produces must be a substantive, on-topic sentence from the body text (abstract, results, or discussion) that a reader could point to and say "yes, this is where the claim comes from." ## Workflow 1. **Read the manuscript.** Extract, in order of first appearance, every in-text citation number and the exact sentence/claim each one is attached to. A single citation is often reused for more than one claim later in the document — track each occurrence separately. 2. **Read the reference list** and map citation number → paper (authors, title, journal, year). Confirm the reference list order matches first-appearance order in the text; if not, that's a separate numbering bug to flag (see `references/gotchas.md`). 3. **For each citation, for each claim it's attached to:** - Open the corresponding PDF. Skip publisher cover/landing pages and running headers; find the real body text (abstract, results, discussion). - Search the extracted text for the sentence that actually states the claim — use the literal text as extracted (see OCR caveat below), not a manually retyped "clean" version. - If found: highlight exactly that sentence using `scripts/highlight_pdf_quote.py`. - If not found after a genuine search of the abstract/results/discussion: **stop and report it** rather than highlighting the nearest loosely-related passage. State plainly what the paper is actually about and why it doesn't support the claim. Let the user decide (see step 5). 4. **Do a final consistency pass** once all individual highlights are done: re-derive the citation order from the manuscript text, confirm it matches the reference list and the PDF filename numbering 1..N with no gaps, and spot-check a couple of the highlights against their claims again. Report results as a table: citation # → paper → claim it supports → confirmed/flagged. 5. **When a citation is flagged as a mismatch**, ask the user (don't decide unilaterally): - Remove it from that citation group entirely (if the remaining citations in the group already cover the claim) - Move it to a different sentence in the manuscript that its real content *does* support - Leave as-is for now If the user chooses removal: delete the reference from the list, delete its PDF, renumber every citation/reference/filename after it by one, and re-run the final consistency pass. ## Reusable scripts - `scripts/highlight_pdf_quote.py` — given a PDF path and one or more target text snippets, optionally clears existing highlight annotations first, then adds a highlight exactly on each matched snippet. Reports which targets were/weren't found so a failed match is visible immediately, not silently skipped. - `scripts/audit_pdf_highlights.py` — lists every current highlight annotation across one PDF or a whole folder, with the text under each one, for a quick before/after sanity check. Writes to a UTF-8 file rather than stdout (see console-encoding gotcha). ## Before you start Read `references/gotchas.md` — it covers the specific technical failure modes (hyphenated line-wraps breaking search, OCR-garbled old scans, scrambled multi-column text extraction, console encoding crashes on non-ASCII author names) that will otherwise cost several retries per PDF.