High-accuracy PDF content extraction for Claude Code — formulas, images, tables
为 Claude Code 补充复杂 PDF 的高精度内容解析能力
Claude Code's default pdf skill relies on pypdf + pdfplumber. Fine for simple documents, but falls short on complex ones:
| Scenario | What actually happens |
|---|---|
| Math formulas | pypdf outputs garbage like PrðfðXÞ/C0 ... — completely unusable |
| Image extraction | pdfplumber / pypdf cannot extract images; pdfimages gives raw binaries with no position info |
| Output format | Plain text, losing heading hierarchy, reading order, and image-caption associations |
| Scanned PDFs | Entirely dependent on pytesseract with tedious setup and mediocre results |
Does not replace the official pdf skill. mineru-pdf is a standalone skill — use it explicitly when you need high-quality extraction.
Simple PDFs (plain text / single column) → default pdf skill (pypdf, sub-second)
Complex PDFs (formulas / multi-column / scanned) → this skill (MinerU, high accuracy)
- Editing operations (merge, split, watermark, encrypt) stay with the official pdf skill
- Content extraction with formulas, images, or complex layouts → this skill
- Installed independently — won't conflict with or be overwritten by marketplace updates
Powered by MinerU (Shanghai AI Lab), running entirely locally — no API keys, no usage limits.
Tested on a dual-column academic paper (PAMI 2004, 7 pages, formulas and figures throughout):
| Dimension | pypdf | MinerU |
|---|---|---|
| Formula extraction | PrðfðXÞ/C0 /C22 /C21 /C28 Þ/C20 ... garbled |
\mathrm{Pr}(f(\mathbf{X})-\mu\geq\tau) \leq ... compilable LaTeX |
| Image extraction | None | 21 image files (13 figures + 8 elements) + bbox coordinates + captions |
| Time | < 1 sec | ~ 3 min (first run downloads models) |
| Output | Raw text string | Markdown + JSON + Images |
All data is from actual tests on the same paper — reproducible.
Prerequisites: Python 3.8+, Claude Code installed
- macOS / Linux: Open Terminal
- Windows: Press
Win + R, typepowershell, press Enter
pip install "mineru[pipeline]"Pulls in torch, transformers, etc. First install takes 3-5 minutes.
macOS / Linux:
mkdir -p ~/.claude/skills/mineru-pdf && curl -o ~/.claude/skills/mineru-pdf/SKILL.md https://raw.githubusercontent.com/hawkongz/mineru-pdf/master/SKILL.mdWindows (PowerShell):
New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills\mineru-pdf"; Invoke-WebRequest -Uri "https://raw.githubusercontent.com/hawkongz/mineru-pdf/master/SKILL.md" -OutFile "$env:USERPROFILE\.claude\skills\mineru-pdf\SKILL.md"Restart Claude Code, then:
/mineru-pdf extract this PDF
On first use, MinerU auto-downloads models (~2 GB from HuggingFace), cached permanently thereafter.
Type /mineru-pdf followed by your PDF path and needs. The skill auto-detects whether formula recognition, OCR, etc. are needed.
| Signal | Action |
|---|---|
pypdf output has /Cxx escape codes |
/mineru-pdf |
| PDF contains math formulas, Greek letters | /mineru-pdf |
| Multi-column layout — reading order matters | /mineru-pdf |
| Need images with position metadata | /mineru-pdf |
| Scanned PDF (image-based, no text layer) | /mineru-pdf |
| Plain text, single column, no formulas | Default pdf skill is faster |
claude-code pdf-parsing mineru skill document-parser ocr latex
Issues and PRs welcome. Test changes to SKILL.md with at least one complex PDF in Claude Code before submitting.
See CONTRIBUTING.md for guidelines.
MIT — see LICENSE.
The MinerU engine is licensed under AGPL-3.0.
Made with ❤️ for the Claude Code community