pdf-tools — Claude Code skill for PDF generation, extraction and forms
pdf-tools — a skill for Claude Code, Codex, Cursor, GitHub Copilot and Gemini CLI that covers the full PDF lifecycle: text and table extraction, generation, modification, form filling and encryption.
MIT 186 installs ★ 29 updated 2026-08-17
npx skills add oakoss/agent-skills --skill pdf-tools -a claude-codeWhat pdf-tools does
The skill gives the agent a concrete tool map: Puppeteer and Playwright for HTML-to-PDF generation, pdf-lib and its fork @cantoo/pdf-lib for merging, splitting and writing AcroForm fields, unpdf for lightweight extraction in edge and serverless contexts, pdfplumber in Python for tables with complex layouts. Encryption goes through qpdf with AES-256; digital signatures use @signpdf/* with PKCS#7 and P12 certificates.
The skill distinguishes cases where standard parsers fall short. Multi-column text and merged cells route to a vision model with a Zod schema or to pdfplumber. Non-fillable forms go to Python annotation scripts using bounding box coordinates. PDF/A archival compliance uses ghostscript for conversion and verapdf for validation. Batch queue processing is covered with BullMQ backed by Redis.
Common mistakes are listed explicitly: using window.print() server-side, running Puppeteer in edge environments, writing to flattened form fields without inspecting AcroForm first. For redaction that actually removes content bytes, the skill points to pymupdf with apply_redactions(), because a visual overlay leaves the data in the file.
What it helps with
- extract merged-cell tables from a PDF using a vision model and Zod schema
- generate a pixel-accurate PDF from a React HTML template with Puppeteer
- fill a non-fillable PDF form using bounding box annotation scripts
- encrypt a PDF with AES-256 via qpdf before uploading to storage
- set up a BullMQ batch queue for PDF processing with retries and progress tracking
Example prompts for the agent
- Extract the table from
report.pdfusing the vision model and return it as a Zod-validated structure - Generate a PDF from
invoice.htmlwith Puppeteer and embed fonts from the WOFF2 files - Encrypt
contract.pdfwith AES-256 usingqpdf, setting separate user and owner passwords
How to install pdf-tools
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill pdf-tools -a claude-code2Manually: put the files in place
~/.claude/skills/pdf-tools/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/pdf-tools/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill pdf-tools -a codex2Manually: put the files in place
.agents/skills/pdf-tools/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill pdf-tools -a cursor2Manually: put the files in place
.cursor/skills/pdf-tools/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install oakoss/agent-skills skills/pdf-tools2Manually: put the files in place
.github/skills/pdf-tools/SKILL.md1Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill pdf-tools -a gemini-cli2Platform CLI
gemini skills install https://github.com/oakoss/agent-skills --path skills/pdf-toolsManually: put the files in place
.devin/skills/pdf-tools/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add oakoss/agent-skills --skill pdf-tools -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about pdf-tools
How do I install pdf-tools in Claude Code?
Run npx skills add oakoss/agent-skills --skill pdf-tools -a claude-code. The skill is placed at ~/.claude/skills/pdf-tools/SKILL.md.
What does the pdf-tools skill do?
It gives the agent a tool map for the full PDF lifecycle: extraction, HTML-to-PDF generation via Puppeteer, modification via pdf-lib, form filling, AES-256 encryption and digital signatures.
Does pdf-tools work in edge or serverless environments?
unpdf is edge-compatible, so extraction works there. Puppeteer requires a full Node.js runtime and cannot run in edge environments — the skill routes these cases separately.
Source text
SKILL.md · MIT
--- name: pdf-tools description: 'PDF engineering for extraction, generation, modification, and form filling. Use when extracting text or tables from PDFs, generating PDFs with Puppeteer, modifying PDFs with pdf-lib, filling PDF forms, or implementing PDF security. Use for AI-assisted OCR, HTML-to-PDF conversion, and document processing pipelines.' license: MIT metadata: author: oakoss version: '1.1' --- # PDF Tools Full-lifecycle PDF engineering covering extraction, generation, modification, form filling, and security. Prioritizes JavaScript-first solutions (pdf-lib, unpdf, Puppeteer) with Python/CLI utilities for advanced scenarios. **When to use**: Extracting structured data from PDFs, generating pixel-perfect PDFs from HTML/React, modifying existing PDFs, filling forms (fillable or non-fillable), or securing documents with encryption. **When NOT to use**: Simple text file processing, image-only manipulation without PDF context, or tasks better handled by a word processor. ## Quick Reference | Task | Tool | Key Point | | -------------------------- | ----------------------------- | -------------------------------------------------------------------------- | | Generate PDF from HTML | Puppeteer / Playwright | `page.pdf()`; use `networkidle0` (Puppeteer) or `networkidle` (Playwright) | | Extract text (lightweight) | unpdf | Edge/serverless compatible | | Extract tables (AI) | Vision model + Zod schema | Multi-column and merged cell support | | Extract tables (non-AI) | pdfplumber (Python) | Precise cell boundary detection | | Modify, merge, split | pdf-lib (or `@pdfme/pdf-lib`) | Byte-level PDF manipulation in JS | | Fill fillable forms | pdf-lib (or `@pdfme/pdf-lib`) | Inspect AcroForm fields before writing | | Fill non-fillable forms | Python annotation scripts | Visual analysis + bounding box annotations | | Encrypt PDF | qpdf | AES-256: `qpdf --encrypt user owner 256 --` | | Repair corrupted PDF | qpdf | `qpdf input.pdf --replace-input` | | Fast text extraction (CLI) | poppler-utils | `pdftotext -layout input.pdf -` | | Merge thousands of files | pypdf (Python) | Lighter than headless browser | | Batch queue processing | BullMQ + unpdf | Redis-backed with retry, concurrency, progress tracking | | PDF/A archival compliance | ghostscript + verapdf | `gs -dPDFA=2` for conversion; verapdf for validation | | Tagged PDF (accessibility) | Puppeteer | `tagged: true` maps HTML semantics to PDF structure tags | | Digital signatures | @signpdf/\* | PKCS#7 signing with P12 certificates | | PDF comparison | unpdf + diff / pixelmatch | Text diff or pixel-level visual diff between versions | | Secure redaction | pymupdf (fitz) | `apply_redactions()` removes content bytes, not just visual overlay | ## Common Mistakes | Mistake | Correct Pattern | | ------------------------------------------------------ | ----------------------------------------------------------------- | | Using canvas drawing commands for PDF generation | Use Puppeteer/Playwright with HTML/CSS templates | | Running Puppeteer in edge/serverless environments | Use unpdf for edge; Puppeteer requires full Node.js | | Extracting complex layouts with basic text parsers | Use AI-assisted OCR or pdfplumber for multi-column text | | Storing unencrypted PDFs with PII in public storage | Apply AES-256 encryption via qpdf before storage | | Relying on `window.print()` for server-side generation | Use headless browser APIs (`page.pdf()`) for deterministic output | | Using pypdf for complex layout extraction | Use pdfplumber or AI OCR for multi-column or overlapping text | | Skipping font embedding in containerized environments | Embed Google Fonts or WOFF2 files with Puppeteer | | Writing to flattened PDF form fields | Inspect AcroForm fields with pdf-lib before writing | | Using unmaintained `pdf-lib` for encrypted PDFs | Use `@cantoo/pdf-lib` fork which adds encrypted PDF support | ## Delegation - **Inspect PDF structure and diagnose extraction issues**: Use `Explore` agent to examine AcroForm fields, encoding, and metadata - **Build end-to-end document processing pipelines**: Use `Task` agent to implement extraction, transformation, and generation workflows - **Design PDF architecture for a new system**: Use `Plan` agent to select tools and plan extraction, generation, or modification strategies ## References - [AI Extraction Patterns](references/ai-extraction-patterns.md) -- Vision-based table extraction, recursive summarization, multi-pass verification - [High-Fidelity Generation](references/high-fidelity-generation.md) -- Puppeteer HTML-to-PDF, CSS print tips, React templates, browser pooling - [Legacy Utilities](references/legacy-utilities.md) -- pdfplumber, pypdf, qpdf, poppler-utils for batch and forensic tasks - [Form Filling](references/form-filling.md) -- Fillable field extraction, non-fillable annotation workflow, validation scripts - [Batch Processing and Accessibility](references/batch-and-accessibility.md) -- Queue-based batch processing, PDF/A compliance, tagged PDFs, digital signatures, comparison, redaction
© oakoss · MIT · oakoss/agent-skills