pdf-to-md

name	pdf-to-md
version	1.1.0
description	Convert PDF to Markdown so Claude can read it natively in conversations. Three-tier engine: pymupdf4llm (fast, default), marker-pdf (--quality, Apple MPS-accelerated for scanned/equations), docling (--best, IBM, top accuracy on academic/enterprise PDFs). Auto-extracts images. Use when the user pastes a PDF path, asks "read this paper", "convert this PDF", "summarize this report", or whenever a .pdf needs to enter context.
triggers	["convert pdf to markdown","read this pdf","summarize this paper","pdf to md","parse this pdf"]
allowed-tools	["Bash","Read","Write"]

PDF → Markdown

When to use

Whenever a .pdf file appears in the conversation and the user wants Claude to read, summarize, quote, or operate on its contents. Native Read tool can open small PDFs but truncates large ones and loses table structure — this skill produces a clean .md you can read fully and grep.

How to invoke

One command does everything (auto-installs missing deps on first run):

python3 ~/.claude/skills/pdf-to-md/bin/convert.py <path-to-pdf>

Output: writes <same-dir>/<same-name>.md next to the PDF, plus an <same-name>_images/ folder if images are extracted.

Common flags:

• --quality — force the marker-pdf engine (use for scanned PDFs, academic papers with equations, or when the fast engine output looks sparse)
• --out <path> — override output path
• --engine pymupdf4llm|marker — pick engine explicitly
• --no-images — skip image extraction

After conversion, Read the produced .md.

Engine selection (auto)

PDF type	Engine	Why
Native (most modern PDFs, has selectable text)	pymupdf4llm	<30s install, no models, fastest, ~520 pages/sec
Scanned (no extractable text detected)	auto-fallback to marker-pdf	Has OCR + layout model
Heavy LaTeX / complex tables	use --quality to force marker-pdf	LLM-optimized table + equation extraction

The script auto-detects scanned PDFs (text density check) and switches engines without user intervention.

First-run gotchas (tell the user)

• pymupdf4llm: installs in ~15s, no model download. Just works.
• marker-pdf: first run downloads ~2GB of models from HuggingFace. Subsequent runs are fast. If on slow wifi, warn the user before triggering --quality.
• Apple Silicon: both tools have prebuilt wheels — no compilation needed.

Examples

# Quick read — fast engine, default output
python3 ~/.claude/skills/pdf-to-md/bin/convert.py ~/Downloads/paper.pdf

# Academic paper with equations — force quality engine
python3 ~/.claude/skills/pdf-to-md/bin/convert.py ~/Downloads/paper.pdf --quality

# Custom output path, no images
python3 ~/.claude/skills/pdf-to-md/bin/convert.py report.pdf --out /tmp/report.md --no-images

What this skill does NOT do

• Does not handle Office docs (use markitdown or pandoc for .docx/.pptx)
• Does not call cloud APIs (LlamaParse, Mistral OCR) — pure local. Add a flag later if bulk volume requires it.
• Does not transcribe handwritten PDFs (Tesseract-grade OCR only).