read-pdfs — token-efficient PDF reading skill for Claude

A Claude Agent Skill that lets Claude read, search, summarize, quote, and extract tables from existing PDFs without loading the whole file into context.

No more burning quota and tokens dumping whole PDFs into context — one command builds a token-light workspace per PDF, reads the cheap Markdown, and only renders the page(s) whose visuals actually matter.

Install

Install into any Agent Skills–compatible tool (Claude Code and others) via the skills.sh CLI:

npx skills add brainqub3/read-pdfs

This copies the skill into your agent's skills directory (e.g. ~/.claude/skills/). You can also clone this repo and run the scripts directly — see Quick start.

What it does

1. Ingest once — converts a PDF into a self-contained workspace folder: structured Markdown (text, headings, tables) plus the original PDF and a manifest.json.
2. Placeholders, not pixels — every image, figure, chart, or diagram becomes a small page-anchored placeholder (🖼 [[fig:p4:1]]) instead of being embedded.
3. Render on demand — when a visual actually needs to be seen, only that one page is rendered to a PNG.

Token cost then scales with what you look at, not with the size of the PDF. See skills/read-pdfs/SKILL.md for the full skill instructions.

Repository layout

read-pdfs/                                  # repo root
├── README.md
├── LICENSE
└── skills/
    └── read-pdfs/                          # the skill (skills.sh flat layout)
        ├── SKILL.md                        # skill instructions + frontmatter
        ├── requirements.txt
        ├── scripts/
        │   ├── pdf_to_markdown.py          # PDF -> Markdown workspace + placeholders
        │   └── render_page.py              # render specific page(s) to PNG on demand
        ├── references/
        │   ├── placeholders.md             # placeholder/token format + figure index
        │   └── conversion-internals.md
        └── evals/
            ├── evals.json                  # test scenarios
            └── fixtures/                   # runnable sample.pdf (+ generator)

Quick start

# 1. Install the Python dependencies
pip install -r skills/read-pdfs/requirements.txt

# 2. Convert a PDF into a workspace folder (report/ next to the PDF)
python skills/read-pdfs/scripts/pdf_to_markdown.py path/to/report.pdf

# 3. Read report/report.md (text + figure index + placeholders)

# 4. Render a page only when you must see a visual, then open the PNG
python skills/read-pdfs/scripts/render_page.py path/to/report 4

In Claude, once installed, just ask to read / summarize / analyze a PDF and the skill triggers automatically.

Dependencies

pymupdf4llm (structured Markdown) and pymupdf (rendering & extraction), installed via requirements.txt. Requires Python 3.8+.

Note: PyMuPDF is licensed AGPL-3.0 / commercial; review its license before redistributing.

License

MIT © Brainqub3 — see LICENSE