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):

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: