# PDF Explore > Use this skill when the user has attached or pointed to a PDF, paper, report, or other document and the answer needs content from more than one place in it: summarize the methods or any other section, compare sections, find where a topic is discussed, read a value or label off a figure or chart, pull tables out as CSV, or find/list/extract every instance of something across the whole document (datasets, benchmarks, citations, figures, table rows, accession numbers — including appendices). It parses the PDF once in Python: pdf_pages (pages as persistent text), pdf_outline (TOC), pdf_tables (deterministic table extraction with per-table page provenance), pdf_images (embedded figures at native resolution), and prepare/assemble helpers that fan whole-doc relevance scans / per-page maps / structured extraction out over Task subagents so the pages never fill your own context. Complementary to the built-in Read(pages=...), which attaches ≤20 PDF pages as ephemeral vision dropped after one turn — reach for this skill - Skill: `emaballarin/pdf-explore` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add emaballarin/pdf-explore` - Raw SKILL.md: https://api.skillmd.com/api/skills/emaballarin/pdf-explore/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Data & Analytics - License: Apache-2.0 - Author: emaballarin (https://skillmd.com/u/emaballarin) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/emaballarin/pdf-explore --- # PDF Explore — navigate a PDF too big to embed The built-in `Read(file_path=..., pages=[...])` attaches PDF pages as vision blocks — capped at ~20 pages/turn and **dropped from context after one turn**, so multi-section synthesis turns into re-reading the same pages over and over. And when the answer is "every page" (list all datasets / citations / figures mentioned anywhere), reading the whole document page-by-page is the expensive way to get it. This skill parses the PDF **once** into persistent per-page text, and — for whole-document work — runs **one cheap model call per page (or per batch) in parallel via Task subagents**, so the page text lives in files and subagent contexts, never in yours. You load only what matters, or sweep every page without putting the pages in your own context at all. `Read(pages=...)` and this skill are **complementary**: use `Read(pages=...)` for a one-off look at 1–4 pages you will quote in your very next reply; use this skill for persistent text, multi-section synthesis, whole-doc sweeps, and structured extraction. ## Loading the kernel The helpers live in `kernel.py` next to this file. It is **not** auto-injected — import it by path in a Bash `python` heredoc (zero import-time side effects, all heavy imports are lazy): ```bash python3 - <<'PY' import importlib.util K = "/ABSOLUTE/PATH/TO/pdf-explore/kernel.py" # this SKILL.md's directory + /kernel.py spec = importlib.util.spec_from_file_location("pdf_kernel", K) k = importlib.util.module_from_spec(spec) spec.loader.exec_module(k) for e in k.pdf_outline("paper.pdf"): print(f"p{e['page']:>3} {' ' * (e['level'] - 1)}{e['heading']}") PY ``` Every recipe below assumes `k` is loaded this way. Each `python` invocation is a **fresh process** — the in-memory page cache does not survive between them, but page renders are cached on disk and re-extracting the text layer is cheap, so re-parsing the same file in a later call is fast. **Invocation.** The recipes below all open with `python3 - <<'PY'`, which is right when the deps are importable from your `python3`. If they aren't — or you would rather not install anything — prefix with `uv`, which fetches them into a throwaway env: ```bash uv run --with pypdfium2 --with pillow --with pdfplumber python - <<'PY' ``` (Drop `--with pdfplumber` unless you're calling `pdf_tables`.) Otherwise `pip install pypdfium2 pillow` — plus `pdfplumber` for tables — and use plain `python3 -`. Backend note: the default backend is pypdfium2 — Google PDFium, permissive Apache-2.0/BSD-3-Clause. PyMuPDF is honored as a fallback if already installed, but it is AGPL-3.0; if you embed it in a network service, AGPL's source-sharing terms apply. `pdf_tables` is the one helper on a second backend (pdfplumber), because PDFium exposes no table API at all. `path` can be a workspace path or a `~/`-expanded path. ## Which helper — inline vs Task fan-out | helper | when | how the model work happens | | ------------------------------------------------------- | ------------------------------------------------------------------------------- | -------------------------------------------------------------- | | **`Read(pages=[...])`** (built-in, no skill) | one-off look at 1–4 pages you quote in your _very next_ reply | ephemeral vision, ≤20/turn, dropped after the turn | | **`k.pdf_pages(path, pages=[...], mode="text")`** | several pages/sections at once — summaries, comparisons, any multi-range answer | **inline**: you read the text and answer | | **`k.pdf_outline(path)`** | structured doc (paper, report, book) with an embedded TOC | **inline**: free, instant, no model | | **`k.pdf_outline_prepare` / `_assemble`** | build a TOC when there is **no** embedded outline | **fan-out** (one subagent for text ≤150pp, per-page otherwise) | | **`k.pdf_scan_prepare` / `_assemble`** | semantic query → the K most relevant pages | few pages **inline**; many pages **fan-out** | | **`k.pdf_map_prepare` / `_assemble`** | free-text answer of _every_ page (transcript, slide dump) | **fan-out** | | **`k.pdf_extract_prepare` / `_assemble`** | **exhaustive list of X across the whole doc** (datasets, citations, table rows) | **fan-out** | | **`k.pdf_tables(path)`** | **tables** — deterministic parse, page provenance, full table → CSV | **inline**: no model, no vision | | **`k.pdf_images(path)`** → `Read` | a **raster** figure/photo/plot, at its native resolution | you `Read` the extracted image | | **`k.pdf_pages(mode="image")` → `k.pdf_crop` → `Read`** | a **vector** figure, or any region `pdf_images` can't see | you `Read` the saved crop | "Inline" = you read the page text (or figure crop) yourself and produce the answer in the same turn. "Fan-out" = the two-phase protocol below. ## The fan-out protocol (scan / map / extract / outline over many pages) Three steps. The page text never enters your context — it goes to files that subagents read. 1. **PREPARE** — call the `*_prepare` helper. It parses the PDF, writes the guarded page text into batched work files, and returns a small JSON manifest: `instruction`, (`query` / `schema` where relevant), `return_spec`, and `items` = `[{pages, text_file, image_paths}, ...]`. Only this small manifest lands in your context. 2. **FAN OUT** — for each `item`, launch a **Task** subagent. Its prompt = the manifest's `instruction` (+ `query` / `schema`) + _"Read `text_file` (and Read each non-null `image_paths` entry), then return ONLY the JSON the `return_spec` describes."_ Each subagent returns a short JSON array — one object per page it handled. Launch the subagents in parallel. 3. **ASSEMBLE** — concatenate every subagent's array into one flat list, save it to `results.json`, and call the matching `*_assemble` helper. It ranks / merges / de-duplicates and returns the final result. **Batch to keep the subagent count sane.** `batch_size=N` packs N pages into one work file → one subagent scores/summarizes all N. For a 120-page doc, `batch_size=15` means 8 subagents, not 120. Default is 1 (one page per subagent); raise it for anything over ~20 pages. A subagent handling untrusted document text returns **data** (scores / summaries / fields), never actions — and the work files wrap page text in per-job nonce delimiters the document can't forge, so a page that says "ignore your instructions" is inert. ### Worked example — relevance scan of a whole paper ```bash # 1. PREPARE python3 - <<'PY' import importlib.util, json K = "/ABSOLUTE/PATH/TO/pdf-explore/kernel.py" spec = importlib.util.spec_from_file_location("pdf_kernel", K) k = importlib.util.module_from_spec(spec); spec.loader.exec_module(k) m = k.pdf_scan_prepare("paper.pdf", query="batch-effect correction methods", batch_size=10) print(json.dumps(m, ensure_ascii=False, indent=1)) PY ``` 2. Read the manifest. For each `item`, launch a Task subagent, e.g.: > `{instruction}` `{query}` — Read the page text at `{text_file}`. For each > page in it, score relevance in [0,1] and write one sentence on what the > page contains. Return ONLY a JSON array `[{"page":N,"score":x,"summary":"…"}]`, > nothing else. Collect the arrays, concatenate them, and `Write` the flat list to `results.json`. ```bash # 3. ASSEMBLE python3 - <<'PY' import importlib.util K = "/ABSOLUTE/PATH/TO/pdf-explore/kernel.py" spec = importlib.util.spec_from_file_location("pdf_kernel", K) k = importlib.util.module_from_spec(spec); spec.loader.exec_module(k) r = k.pdf_scan_assemble("paper.pdf", "results.json", top_k=5) for h in r["hits"]: print(f"p{h['page']} {h['relevance']:.2f} {h['summary'] or h['text'][:100]}") print(f"[{r['n_scanned']} pages scanned]") PY ``` `pdf_scan_assemble` re-attaches each hit's persistent text, so you can then read the top pages' `text` directly, or `Read(file_path='paper.pdf', pages=[...])` the few winners as vision. Pass `threshold=0.7` instead of `top_k` to keep every page above a score. **When only a handful of pages are in play, skip the fan-out** — print their text and scan/extract inline: ```bash python3 - <<'PY' ... load k ... for p in k.pdf_pages("paper.pdf", pages=[4, 5, 6, 7], mode="text"): print(f"\n== p{p['page']} ==\n{p['text'][:2000]}") PY ``` Then answer from that output — no subagents needed. ## Recipe — pull the sections you need as persistent text (synthesis) For "summarize the methods" / "compare section 3 and section 5" — anything drawing on several page ranges at once — pull **all** the pages in one call, write them to a file, then `Read` that file (persistent, unlike vision pages): ```bash python3 - <<'PY' ... load k ... import os wanted = [5, 21, 22, 23, 24, 25, 62, 63, 64] # from pdf_outline with open("sections.txt", "w") as f: for p in k.pdf_pages("paper.pdf", pages=wanted, mode="text"): f.write(f"\n── page {p['page']} ──\n{p['text']}") print(f"wrote {os.path.getsize('sections.txt'):,} bytes") PY ``` Then `Read(file_path="sections.txt")` (with `offset`/`limit` if over ~100KB) and write the answer from that. ~800 tokens/page as text vs ~4,000/page as vision — and it stays in context. **Don't `print()` a whole chapter directly**; write it to a file and `Read` it. For a quick look at ≤5 pages, printing is fine. ## Recipe — navigate by outline (try this first) ```bash python3 - <<'PY' ... load k ... for e in k.pdf_outline("report.pdf"): print(f"p{e['page']:>3} {' ' * (e['level'] - 1)}{e['heading']}") PY ``` Free and instant when the PDF has an embedded outline (most LaTeX-compiled papers do). If `pdf_outline` returns `[]` (no embedded outline), it prints a hint: rebuild the TOC with the fan-out protocol using `pdf_outline_prepare(path)` → subagents → `pdf_outline_assemble(results, n_pages=…)`. `pdf_outline_prepare` auto-picks a single holistic subagent for text-layer docs ≤150pp, or per-page subagents for scanned/long docs; each subagent returns `[{"page","heading"}]` (single-call) or `[{"page","section_headings":[...]}]` (per-page), and `pdf_outline_assemble` infers levels and de-duplicates. For a semantic question the outline doesn't obviously answer ("where do they discuss limitations"), use the scan protocol. ## Recipe — read a figure in detail A full rendered page downsamples to ≤1568px on attach, so a dense figure ends up illegible no matter the DPI. There are two ways out, and **which one works depends on how the figure was drawn**. ### First try `pdf_images` — the figure at its native resolution If the figure is a **raster** (a photo, a screenshot, an exported PNG/JPEG plot — most non-LaTeX papers), it is embedded in the PDF as an image object and you can pull the original pixels straight out. That beats cropping a page render, because the page render already threw resolution away: ```bash python3 - <<'PY' ... load k ... for e in k.pdf_images("paper.pdf", pages=[5]): print(f"p{e['page']} idx{e['index']} {e['px_size']} {e['bbox']} -> {e['image_path']}") PY ``` Then `Read(file_path="")`. Results come back largest-first, so the real figures lead and decoration trails. A logo repeated on every page collapses to one entry whose `pages` lists them all; anything with a side under `min_px` (64) is dropped as decoration. Concretely, on a typical paper the page-1 figure is embedded at **2372×1359**, while the whole page rendered at 100 dpi is only 788×1075 — so a crop of that figure would be roughly 570×326. Same figure, ~4× the linear detail, for less work. ### Fall back to render + crop for vector figures **`pdf_images` only sees raster objects.** A TikZ / pgfplots / matplotlib-PDF figure is _drawing operations_, not an image — it will not appear, and `pdf_images` returning `[]` on a figure-rich LaTeX paper is the expected, correct answer, not a bug. For those, rasterize the page yourself and crop: ```bash python3 - <<'PY' ... load k ... # Render page 5 at dpi=200 (lands in .cache/, not attached), then crop. p = k.pdf_pages("paper.pdf", mode="image", pages=[5], dpi=200)[0] print("page render:", p["image_path"]) crop = k.pdf_crop(p["image_path"], (x0, y0, x1, y1)) # pixels in the dpi=200 render print("crop:", crop) PY ``` Then `Read(file_path="")` — more legible _and_ cheaper than the full page (~400 vision tokens vs ~1,600). First `Read` the full page render to locate the figure if you don't know its box; crop one panel at a time for multi-panel figures. Always crop from the `.cache/` render, never from a previously attached (downsampled) view. ### Fidelity note `pdf_images` defaults to `render=True`, saving the image **as pdfium composites it** — alpha and masks applied, so what you `Read` is what the page shows. Pass `render=False` to write the original encoded bytes instead (lossless for JPEG/JPEG-2000, and much smaller), but pdfium's raw extraction **ignores alpha masks**, so a figure with transparency can come out visibly wrong. Prefer the default when you are going to _read_ the figure; use `render=False` when you want the original asset. ## Recipe — extract tables `pdf_tables` parses tables **deterministically** — no model, no vision, no fan-out — and every table comes back tagged with the page it came from: ```bash python3 - <<'PY' ... load k ... # needs pdfplumber: uv run --with pdfplumber ... for t in k.pdf_tables("paper.pdf"): print(f"p{t['page']} #{t['index']} {t['n_rows']}×{t['n_cols']} -> {t['csv_path']}") for row in t["rows"]: # preview only, capped print(" ", row) PY ``` The **full** table is written to `csv_path`; only a `preview_rows`-capped preview comes back inline, so a 300-row table never lands in your context. When you actually need all of it, `Read` the CSV (or `pandas.read_csv` it) — same rule as the rest of the skill: bulk goes to a file, not into the conversation. Detection defaults to ruled lines. For a whitespace-aligned table with no rules, pass `table_settings={"vertical_strategy": "text", "horizontal_strategy": "text"}`. Ruled-line detection also fires readily on boxed captions and framed paragraphs, which arrive as n×1 "tables" — the `min_rows`/`min_cols` floor (2×2) drops those; lower `min_cols=1` if you genuinely want single-column boxes. **Prefer this over a schema fan-out for tables.** A `pdf_extract_prepare` sweep with `{rows:[{col1,col2}]}` pays a model per page to re-derive structure that pdfplumber reads off the page geometry for free — and gets ruled tables wrong often enough to matter. Reach for the fan-out only when what you want isn't the table grid but a _judgment_ about it. ## Recipe — map every page For docs with no useful section structure (transcripts, slide exports), summarize every page with the fan-out protocol and `pdf_map_prepare` / `pdf_map_assemble`. Each subagent returns `[{"page","text"}]`; `pdf_map_assemble("doc.pdf", "results.json")` returns `{pages:[{page,text,n_chars,image_path}], n_pages}` in page order. Nothing is filtered out, so no relevant page is missed. Then pick pages and `Read` them. ## Recipe — structured extraction (exhaustive list of X) Pull the same fields from every page, in parallel, with `pdf_extract_prepare` / `pdf_extract_assemble`. Pass a JSON-Schema object; each subagent returns `[{"page","data":{…}}]`, then flatten + dedupe in your own context: ```bash python3 - <<'PY' ... load k ... import json m = k.pdf_extract_prepare("paper.pdf", { "type": "object", "properties": { "figures": {"type": "array", "items": {"type": "object", "properties": {"label": {"type": "string"}, "caption": {"type": "string"}}}}, }, "required": ["figures"], }, batch_size=10) print(json.dumps(m, ensure_ascii=False, indent=1)) PY # … fan out subagents (they get instruction + schema, Read text_file, return # [{"page","data":{...}}]) → concatenate to results.json … python3 - <<'PY' ... load k ... rows = k.pdf_extract_assemble("results.json") figs = [(r["page"], f) for r in rows for f in (r["data"] or {}).get("figures", [])] for pg, f in figs: print(pg, f.get("label"), "—", (f.get("caption") or "")[:80]) PY ``` **Put the inclusion criterion in the schema field's `description`** — e.g. `"datasets on which results are actually reported on this page, not datasets merely cited"`. The per-page subagent applies it for you; leaving it out means re-reading pages later to apply it yourself. **Schemas that work well**: `{figures:[{label,caption}]}`, `{citations:[str]}`, `{section_headings:[str]}`, `{gene_symbols:[str]}` (entity lists). **Schemas that don't**: anything needing judgment about "key" vs "all" (`{key_claims:[str]}` returns ~10/page, unusable) — per-page extraction is recall-complete but precision-noisy. **And not table grids** — use [`pdf_tables`](#recipe--extract-tables), which reads the structure off the page geometry for free instead of paying a model per page to guess at it. **The sweep already read every page.** Don't follow it with `Read(pages=...)` loads to "check for missed items" — that re-spends the tokens the sweep saved. For ≲300 raw names, print the sorted unique names with their page lists and dedupe/normalize while writing the final answer; if you must re-check a few pages, collect them all up front into **one** `pdf_pages(pages=[...])` call (cached, instant) and print their text. ## When NOT to use this skill - **A one-off look at 1–4 pages you quote immediately**: `Read(file_path=..., pages=[...])` is fine — but only if you write your answer that same turn. - **Literal keyword search**: grep the extracted text — `[p for p in k.pdf_pages(path) if "Harmony" in p["text"]]`. The scan protocol earns its cost on _semantic_ queries only. ## Mode (scanned PDFs) All parse helpers default to `mode="auto"`: try text extraction; if pages average < 80 extractable characters (scanned document, image-only slide export), re-parse with page rendering so the subagent can `Read` the page image. You don't need to set this. `"text"`/`"image"` force one or the other; image-mode work files carry `image_paths` for the subagent to `Read`. ## Cost & budget ~800 input + ~100 output tokens/page in text mode. Run the fan-out subagents on a cheap (Haiku-class) model — heavier models cost 10–30× more and add nothing to recall-complete per-page pulls. Token usage isn't visible to the kernel (the calls run inside subagents), so `pdf_scan_cost` reports only `n_calls`/`n_errors`, not tokens. For a very large document, scan a subset via `pages=range(1, n, 3)`, but stride sampling **can miss** a narrow relevant span — prefer `pdf_outline` → read the section when the document has structure. ## Caching `pdf_pages` caches on `(abs_path, mtime, mode, dpi)` **within a single Python process**. Derived assets persist on disk under `./.cache/pdf-explore/{sha8}-{mtime}/`: | subdir | written by | | ------------- | ------------------------------ | | `dpi{N}/` | page renders (`p{NNN}.png`) | | `img/` | `pdf_images` extracted figures | | `tables/` | `pdf_tables` full-table CSVs | | `work/{job}/` | fan-out work files | so a re-render, a re-extract, or a re-prepare after a crash is cheap. The dir is keyed on mtime, so editing the PDF invalidates every stale asset. These are scratch artifacts for the agent to `Read`, not a deliverable — nothing is written outside `.cache/` unless you ask for it.