Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill pdf-tools -a claude-code
Open on GitHub

What 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.pdf using the vision model and return it as a Zod-validated structure
  • Generate a PDF from invoice.html with Puppeteer and embed fonts from the WOFF2 files
  • Encrypt contract.pdf with AES-256 using qpdf, 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-code

2Manually: put the files in place

~/.claude/skills/pdf-tools/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/pdf-tools/

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

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set106

The whole set →

Project sponsors

Companies that keep this analytics open