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

PDF → Markdown

When to use

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