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:
- 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.
- Adds a real PDF highlight annotation on that exact sentence.
- 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.
- 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
- 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.
- 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).
- 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).
- 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.
- 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.
1---2name: highlight-citations3description: 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.4---56# Highlight Citations78## What this does910Given a manuscript with numbered in-text citations (`[1]`, `[1–4]`, etc.) and a folder of the corresponding reference PDFs, this skill:11121. 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.132. Adds a real PDF highlight annotation on that exact sentence.143. 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.154. 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.1617## Why "highlight the title" is not acceptable1819The 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."2021## Workflow22231. **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.242. **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`).253. **For each citation, for each claim it's attached to:**26 - Open the corresponding PDF. Skip publisher cover/landing pages and running headers; find the real body text (abstract, results, discussion).27 - 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.28 - If found: highlight exactly that sentence using `scripts/highlight_pdf_quote.py`.29 - 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).304. **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.315. **When a citation is flagged as a mismatch**, ask the user (don't decide unilaterally):32 - Remove it from that citation group entirely (if the remaining citations in the group already cover the claim)33 - Move it to a different sentence in the manuscript that its real content *does* support34 - Leave as-is for now35 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.3637## Reusable scripts3839- `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.40- `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).4142## Before you start4344Read `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.
Hannah96Z