| name | pdf-analysis |
| description | This skill should be used when the user asks to "extract PDF", "analyze this PDF", "read this paper", "get the table from page X", "extract content from document", "convert PDF to markdown", "what does this PDF say", or mentions PDF page extraction, document analysis, or paper reading. Provides a 3-tier extraction pipeline (pymupdf4llm → Docling MCP → image fallback) with memory-safe single-page workflows.
|
| allowed-tools | Read, Write, Bash, Glob, Grep |
| user-invocable | true |
PDF Analysis
Extract and analyze content from PDF documents using a 3-tier fallback pipeline optimized for accuracy and memory safety.
Page numbering is 0-indexed (first page = 0).
The extraction script is at .claude/skills/pdf-analysis/scripts/extract_page.py relative to the project root.
Extraction Pipeline
Try each tier in order. Advance to the next only when the current tier produces inadequate results.
Tier 1: pymupdf4llm (Fast, Default)
Extract page content as markdown using pymupdf4llm. This is the fastest method and works well for text-heavy pages.
uv run python .claude/skills/pdf-analysis/scripts/extract_page.py <pdf_path> <page> --mode markdown
Evaluate the output. If text reads coherently, tables are recognizable, and key data is present — stop here. Escalate to Tier 2 only if:
- Tables are garbled or structure is lost
- Column text is interleaved
- Layout-dependent content is unreadable
Tier 2: Docling MCP (High-Fidelity Tables)
For pages with complex tables or layouts, use the Docling MCP server. Critical memory constraint: never send a multi-page PDF to Docling.
Step 1 — Extract the target page as a single-page PDF:
uv run python .claude/skills/pdf-analysis/scripts/extract_page.py <pdf_path> <page> --mode pdf --output /tmp/page_<N>.pdf
Step 2 — Convert via Docling MCP:
Use mcp__docling__convert_document_into_docling_document with source /tmp/page_<N>.pdf. This returns a document_key.
Step 3 — Export to markdown:
Use mcp__docling__export_docling_document_to_markdown with the document key.
Timeout/failure — If Docling is slow (>30s) or unresponsive, fall back to Tier 3. Do not retry.
Tier 3: Image + Vision (Universal Fallback)
Render the page as a 200 DPI PNG and analyze visually.
uv run python .claude/skills/pdf-analysis/scripts/extract_page.py <pdf_path> <page> --mode image --output /tmp/page_<N>.png
Then read the image with the Read tool and reconstruct the content as markdown. Preserve numerical values exactly. Describe figures and diagrams.
Quick Start Workflow
-
Get PDF info — determine page count and structure:
uv run python .claude/skills/pdf-analysis/scripts/extract_page.py <pdf_path> --info
-
Extract target pages — start with Tier 1 for each page of interest:
uv run python .claude/skills/pdf-analysis/scripts/extract_page.py <pdf_path> <page> --mode markdown
-
Evaluate and escalate — only move to Tier 2/3 for pages that need it.
When to Skip Tiers
| Situation | Start At |
|---|
| Text-heavy page, no tables | Tier 1 |
| Page with important tables | Tier 1, escalate to Tier 2 if garbled |
| Scanned PDF (no text layer) | Tier 3 directly |
| Diagrams or figures to describe | Tier 3 directly |
| Equations or math notation | Tier 3 directly |
Script Reference
The bundled extraction script supports all three modes:
| Flag | Purpose |
|---|
--info | Show page count and metadata |
--mode markdown | Tier 1: pymupdf4llm extraction |
--mode pdf | Tier 2 prep: single-page PDF for Docling |
--mode image | Tier 3: render as PNG |
--dpi N | Image resolution (default: 200) |
--output PATH | Output file path |
Additional Resources
Reference Files
For backend comparison, troubleshooting, and advanced workflows:
references/extraction-details.md — Detailed backend comparison, Docling MCP invocation steps, multi-page batch patterns, and troubleshooting guide
