# claude-skill-pdf-to-md
A Claude Code skill that converts PDFs to Markdown so Claude can read them natively in conversations. Three engines, one auto-bootstrapping venv, one command.
## Why this exists
Claude Code's native `Read` tool truncates large PDFs and loses table structure. This skill produces a clean `.md` you can read fully, grep, and feed to other tools.
## Quick install
```bash
git clone https://github.com/PHY041/claude-skill-pdf-to-md ~/.claude/skills/pdf-to-md
```
That's it. First invocation auto-creates a venv inside the skill directory and installs the engines on demand. No system Python pollution, no `pipx`, no PEP 668 grief.
## Usage
```bash
python3 ~/.claude/skills/pdf-to-md/bin/convert.py <path-to-pdf>
```
Writes `<name>.md` next to the PDF, plus `<name>_images/` if images are extracted. Returns the output path on stdout.
### Engine choice
| Flag | Engine | When to use |
|------|--------|-------------|
| (default) | **pymupdf4llm** | Fast, zero-model, native PDFs. ~520 pages/sec on CPU. |
| `--quality` | **marker-pdf** | Scanned PDFs, equations, complex tables. Uses **Apple MPS** when available. |
| `--best` | **docling** (IBM) | Highest accuracy on academic/enterprise PDFs. |
| `--engine <name>` | explicit pick | `auto`, `pymupdf4llm`, `marker`, `docling` |
Auto-mode detects scanned PDFs (low text density) and switches to marker without asking.
### Other flags
- `--out <path>` — override output path
- `--no-images` — skip image extraction
## Why three engines
2026 benchmarks (themenonlab, jimmysong) consistently show:
- **pymupdf4llm** wins on speed and zero-setup for native PDFs
- **marker** wins on scanned + equations, with broad device support (MPS/CUDA/CPU)
- **docling** wins on complex enterprise tables and reading-order accuracy
No single engine is best for all PDFs. This skill picks the right one and falls back automatically.
## What this is NOT
- Not a `.docx`/`.pptx` converter — use [microsoft/markitdown](https://github.com/microsoft/markitdown) or `pandoc`
- Not a cloud-API wrapper — purely local, no LlamaParse / Mistral OCR by default
- Not a handwriting OCR tool — Tesseract-grade only
## License
MIT