PyMuPDF grounding skill
An Agent Skill that teaches Claude and other AI agents how to ground answers in PDFs with PyMuPDF. With the skill installed, an agent can find the exact place on the page that supports each claim, return its coordinates, and show it as a highlight or an evidence image, using tested helper code instead of writing its own.
Version 0.2 · Requires pymupdf>=2.1 · Skill content MIT licensed
What the skill does
The result is always a page number and a rectangle in PDF coordinates. Images, highlights and web overlays are ways of displaying that result. Version 0.2 covers two workflows for born-digital PDFs.
Ground LLM citations
- Get the citations. With Claude, send the PDF as a document block with citations enabled. With any other model, a quote and a page hint are enough.
- Locate each quote on the page. Matching is case-insensitive, works across line breaks and rejoins hyphenated words, then falls back to a word-by-word match.
- Return the page number and a rectangle in PDF points, to store with the answer as an audit record.
- Optionally show the evidence: an image of the cited region, or a highlighted copy of the PDF.
RAG chunks with page coordinates
- Build chunks from PyMuPDF's layout boxes instead of plain text, so every chunk keeps the page and position of each part.
- Store the coordinates as flat metadata that LangChain, LlamaIndex and vector stores accept, kept out of embeddings and prompts.
- Show where a retrieved chunk came from as images of its page regions, or send the boxes to your front end.
- Narrow to the exact sentence when the answer quotes the chunk.
Helper functions
The skill includes tested helpers in scripts/grounding.py. The agent copies the functions it needs rather than rewriting them.
| Function | Purpose |
|---|---|
locate(page, text) | Positions of the text on one page, or an empty list |
ground_citations(response, docs) | Locate every page citation in a Claude response |
to_json(results) | Page number and rectangle in PDF points for each citation |
snippet(docs, r, margin=24) | Image of the cited region with surrounding lines |
highlight(docs, results) | Highlight annotations with the claim as the note |
chunks_with_coordinates(path) | Markdown chunks with the page and box of every layout element |
chunk_metadata(path, chunk) | Flat metadata for vector stores: source, page and boxes |
chunk_images(metadata) | Images of the page regions a retrieved chunk came from |
locate_in_chunk(doc, metadata, quote) | Find a quote only inside a retrieved chunk's regions |
The script also works on its own, to check a quote from the command line. It exits with code 1 when the quote is not found:
python scripts/grounding.py report.pdf --quote "Net revenue increased 12%" --page 1 --snippet evidence.pngHow to install the skill
A skill is a folder with a SKILL.md file and its scripts. Install it once and the agent loads it whenever a task involves citing or verifying text in a PDF.
Claude Code
Copy the skill into your personal skills folder so it is available in every project, and install PyMuPDF:
git clone --depth 1 https://github.com/pymupdf/cookbook.git pymupdf-cookbook
mkdir -p ~/.claude/skills/pymupdf-grounding
cp -R pymupdf-cookbook/skills/grounding-skill/. ~/.claude/skills/pymupdf-grounding/
pip install "pymupdf>=2.1"To share it with everyone working on a repository, copy it into the project's .claude/skills folder instead and commit it:
mkdir -p .claude/skills/pymupdf-grounding
cp -R pymupdf-cookbook/skills/grounding-skill/. .claude/skills/pymupdf-grounding/Updating: to get a newer version, pull the latest cookbook and copy the skill again. The copy replaces the existing files:
git -C pymupdf-cookbook pull
cp -R pymupdf-cookbook/skills/grounding-skill/. ~/.claude/skills/pymupdf-grounding/Claude apps (claude.ai and Claude Desktop)
Package the skill folder as a ZIP file:
git clone --depth 1 https://github.com/pymupdf/cookbook.git pymupdf-cookbook
cd pymupdf-cookbook/skills
mkdir -p pymupdf-grounding
cp -R grounding-skill/. pymupdf-grounding/
rm -f pymupdf-grounding.zip
zip -r pymupdf-grounding.zip pymupdf-groundingThen open Settings, go to Capabilities, and upload pymupdf-grounding.zip under Skills. Skills need code execution to be turned on.
Other agents
The skill follows the open Agent Skills format. For agents that support it, copy the grounding-skill folder into the agent's skills folder. For any other agent, add the contents of SKILL.md to its instructions and make scripts/grounding.py available to it.
Using the skill
There is nothing to switch on. Ask for something that needs grounding and the agent uses the skill. In Claude Code you can also call it directly with /pymupdf-grounding. For example:
- “Answer this question from contract.pdf and highlight the passages you cite.”
- “Check that every quote in this answer actually appears in report.pdf.”
- “Chunk these PDFs for my vector store and keep the page coordinates of each chunk.”
Rules the skill follows
- Never presents a citation as evidence when it was not found. It reports found: false and flags it for review.
- Never saves over the original PDF. Highlighted output goes to a new file.
- Does not loosen matching to force a result, so paraphrased quotes are reported as not found.
- Needs a text layer. Scanned pages need OCR first.
License
The skill's instructions and helper code are MIT licensed. PyMuPDF, which the helpers use, is available under the GNU AGPL-3.0 or a commercial license from Artifex. See licensing.