Comprehensive PDF manipulation toolkit. For batch/bulk extraction (1K+ PDFs), use pdftotext (poppler) via subprocess — fastest and most reliable at scale. For single-document understanding, OpenAI Codex PDF-to-Markdown gives best results. Also supports text/table extraction, PDF creation, merging/splitting, and forms.
Best use case
pdf is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Comprehensive PDF manipulation toolkit. For batch/bulk extraction (1K+ PDFs), use pdftotext (poppler) via subprocess — fastest and most reliable at scale. For single-document understanding, OpenAI Codex PDF-to-Markdown gives best results. Also supports text/table extraction, PDF creation, merging/splitting, and forms.
Teams using pdf should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/pdf/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How pdf Compares
| Feature / Agent | Standard Approach | |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Comprehensive PDF manipulation toolkit. For batch/bulk extraction (1K+ PDFs), use pdftotext (poppler) via subprocess — fastest and most reliable at scale. For single-document understanding, OpenAI Codex PDF-to-Markdown gives best results. Also supports text/table extraction, PDF creation, merging/splitting, and forms.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# Pdf
## Overview
This skill enables comprehensive PDF operations through Python libraries and command-line tools. Use it for reading, creating, modifying, and analyzing PDF documents.
## Quick Start
```python
from pypdf import PdfReader
reader = PdfReader("document.pdf")
for page in reader.pages:
text = page.extract_text()
print(text)
```
## Tool Selection (WRK-1277 + WRK-1302 + WRK-1303 Learnings)
### Scenario → Tool Mapping
| Scenario | Tool | Why |
|----------|------|-----|
| Batch extraction (1K+ PDFs) | **pdftotext (poppler)** via subprocess | Proven at 297K scale; reliable timeout via SIGTERM; subprocess isolation |
| Single-doc understanding | **OpenAI Codex** PDF→Markdown | Best quality; too expensive for bulk |
| Single-doc text extraction | **PyMuPDF (fitz)** | Fast, good API, in-process |
| Readability classification | **pypdfium2** | Replaces pdfplumber for page sampling; no D-state hangs; Apache-2.0 license |
| Table extraction | **pdfplumber** (single doc only) | Best table detection; DO NOT use in multiprocessing pools |
| Structured markdown (tables+equations) | **Docling** (targeted use only) | MIT license; 1731 table rows from 6 docs; ~310s/doc on CPU |
| LLM/RAG markdown | **pymupdf4llm** (monitor only) | 0.12s/doc, good markdown; **AGPL license blocks adoption** |
### Quality & Completeness Index (measured on dev-primary)
Scores: text completeness (% of content captured vs best-in-class), structure
preservation, and batch viability. Based on WRK-1302 (243 PDFs) and WRK-1303 (6 PDFs).
| Tool | Text Completeness | Structure | Tables | Equations | Speed | Batch Safe | License |
|------|:-:|:-:|:-:|:-:|:-:|:-:|:-:|
| **pdftotext** (baseline) | 100% | none | none | unicode only | 0.02s | yes | GPL-2 |
| **pypdfium2** | 86% | none | none | unicode only | 0.02s | no (thread-unsafe) | Apache-2.0 |
| **pdfplumber** | ~95% | partial | good (69-93%) | none | 0.10s | no (D-state) | MIT |
| **Docling** | 117% | full (md) | good (md rows) | unicode+context | 310s | no (CPU bound) | MIT |
| **PyMuPDF (fitz)** | ~98% | partial | basic | unicode only | 0.01s | yes | AGPL |
| **pymupdf4llm** | ~100% | full (md) | good (md) | unicode+context | 0.12s | untested | AGPL |
| **Codex API** | ~100% | full (md) | excellent | LaTeX | ~2s | no (API cost) | proprietary |
**Column definitions:**
- **Text Completeness**: chars extracted vs pdftotext baseline (WRK-1302: 243 PDFs, WRK-1303: 6 PDFs)
- **Structure**: none = raw text | partial = some layout | full = headings, lists, sections
- **Tables**: none | basic = cell text only | good = rows+cols preserved | excellent = multi-span
- **Equations**: unicode only = captures symbols | unicode+context = in structured output | LaTeX = formula markup
- **Batch Safe**: can run in ProcessPoolExecutor on NFS/NTFS without hangs or crashes
> **WARNING**: pdfplumber hangs in kernel D-state (disk sleep) on NTFS and NFS mounts.
> SIGALRM cannot interrupt kernel I/O. Use pdftotext via `subprocess.run(timeout=N)` for
> any batch/parallel work — the subprocess can be killed reliably on timeout.
> **Benchmarks**: `scripts/data/doc_intelligence/benchmark_pdf_tools.py` (WRK-1302),
> `scripts/data/doc_intelligence/benchmark_docling.py` (WRK-1303)
## When to Use
- **Batch PDF processing** - Use pdftotext (poppler) via subprocess for bulk extraction
- **Converting PDFs to Markdown** - Use OpenAI Codex for intelligent conversion (single docs)
- Extracting text and metadata from PDF files
- Merging multiple PDFs into a single document
- Splitting large PDFs into individual pages
- Adding watermarks or annotations to PDFs
- Password-protecting or decrypting PDFs
- Extracting images from PDF documents
- OCR processing for scanned documents
- Creating new PDFs with reportlab
- Extracting tables from structured PDFs
## Showing PDF Evidence to the User
When a user asks to "open" or "show" a PDF, prefer direct display, but verify rendering:
1. Try opening the PDF in the browser/viewer using its absolute `file://` path.
2. If the browser PDF viewer renders blank or cannot show the page, convert the relevant page(s) to images with Poppler and return `MEDIA:` links:
```bash
mkdir -p /tmp/pdf-pages
pdftoppm -f 1 -l 1 -png -singlefile "$PDF" /tmp/pdf-pages/document_page_01
pdftoppm -f "$PAGE" -l "$PAGE" -png -singlefile "$PDF" /tmp/pdf-pages/document_page_${PAGE}
file /tmp/pdf-pages/document_page_01.png /tmp/pdf-pages/document_page_${PAGE}.png
```
3. For evidence questions, render both the cover/first page and the controlling clause page so the user can visually verify document identity and operative text.
4. If visual inspection is needed, run image analysis on the rendered page and confirm the visible section/page before reporting.
## Version History
- **1.2.2** (2026-01-04): Fixed P2 issue - added `parents=True` to all `mkdir()` calls to handle nested output paths; prevents FileNotFoundError when creating directories with non-existent parent paths
- **1.2.1** (2026-01-04): Fixed CLI tool missing imports - added complete standalone script with all required imports (openai, pypdf, logging) and function definitions; resolved P1 issue from Codex review
- **1.2.0** (2026-01-04): **MAJOR UPDATE** - Added OpenAI Codex integration for PDF-to-Markdown conversion as recommended first step for all PDF processing; includes batch conversion, chunking for large files, cost-effective options, and complete CLI tool
- **1.1.0** (2026-01-02): Added Quick Start, When to Use, Execution Checklist, Error Handling, Metrics sections; updated frontmatter with version, category, related_skills
- **1.0.0** (2024-10-15): Initial release with pypdf, pdfplumber, reportlab, CLI tools
## Sub-Skills
- [Why Convert to Markdown First?](why-convert-to-markdown-first/SKILL.md)
- [OpenAI Codex Conversion](openai-codex-conversion/SKILL.md)
- [pypdf - Core PDF Operations (+2)](pypdf-core-pdf-operations/SKILL.md)
- [pdftotext (Poppler) (+2)](pdftotext-poppler/SKILL.md)
- [Why Use PDF-Large-Reader? (+8)](why-use-pdf-large-reader/SKILL.md)
- [OCR for Scanned Documents (+3)](ocr-for-scanned-documents/SKILL.md)
- [Execution Checklist](execution-checklist/SKILL.md)
- [Common Errors](common-errors/SKILL.md)
- [Metrics](metrics/SKILL.md)
- [Quick Reference](quick-reference/SKILL.md)
- [Dependencies](dependencies/SKILL.md)Related Skills
test-oversized-skill
A test fixture skill that exceeds 200 lines with multiple H2/H3 sections for split testing.
interactive-report-generator
Generate interactive HTML reports with Plotly visualizations from data analysis results. Supports dashboards, charts, and professional styling.
data-validation-reporter
Generate interactive validation reports with quality scoring, missing data analysis, and type checking. Combines Pandas validation, Plotly visualization, and YAML configuration for comprehensive data quality reporting.
agent-os-framework
Generate standardized .agent-os directory structure with product documentation, mission, tech-stack, roadmap, and decision records. Enables AI-native workflows.
OrcaFlex Specialist Skill
```yaml
repo-ecosystem-hygiene
Interpret the daily read-only repo ecosystem hygiene audit and route remediation through approved workflows.
domain-knowledge-sweep
Systematic multi-source research of an engineering domain. Spawns parent issue → 6 research subissues (Standards, Academic, Industry, LinkedIn-marketing, Code-audit, Synthesis) → gap implementation subissues. Replaces LinkedIn-only extraction with defensible comprehensive sourcing.
subagent-write-verification
Independently verify subagent-claimed file writes with filesystem and git checks before treating the artifact as real, before committing it, and before referencing the path in downstream prompts.
git-operation-serialization-preflight
Before any commit, stash, merge, reset, rebase, or checkout in a multi-agent or shared-checkout environment, run a bounded preflight to detect active git writers and stale index/config locks, then serialize the mutating step under a single-writer guarantee.
public-knowledge-graph-governance
Maintain public-safe knowledge graph artifacts for llm-wiki and similar markdown knowledge bases. Use when changing graph generators, validators, schema docs, weekly freshness checks, or public/private source-scope boundaries.
llm-wiki-weekly-freshness
Class-level governance workflow for keeping llm-wiki-style markdown knowledge bases current, public-safe, graph/index-valid, and useful for code development. Use when reviewing llm-wiki architecture/content, scanning new LLM concepts, maintaining public knowledge graphs, producing an issue roadmap, or running recurring freshness cadence.
llm-wiki-source-extraction-coverage
Doc-type-aware extraction contract for llm-wiki source ingestion with measurable coverage and source-anchored traceability. Use when (1) ingesting a PDF, DOCX, XLSX, PPTX, HTML, or scanned-image source into a wiki `sources/` page, (2) computing the pre-extraction estimate (what fraction of the source we expect to recover) and post-extraction yield (what fraction we actually recovered), (3) anchoring wiki claims back to specific page / paragraph / cell / slide positions in the source so a reviewer can re-verify or revise against the actual document, (4) deciding whether OCR fallback or manual transcription is needed. Codifies workspace-hub's existing OCR fallback chain and python-docx / openpyxl / trafilatura patterns into a format-specific routing table. Companion to research/llm-wiki-page-shape-contract (Rule 7 input-layer pages) and research/llm-wiki — this skill is the defense against silent extraction failure.