PDF is simultaneously everywhere and deeply annoying to work with programmatically. Every developer has a story: the library that generates files fine on Mac but corrupts fonts on Linux, the form-fill script that worked until the PDF was updated, the merge operation that scrambled page order. The Python ecosystem alone has half a dozen PDF libraries — reportlab, fpdf2, pypdf, pdfplumber, weasyprint, cairosvg — and picking the right one for the job requires knowing the differences between them in detail.
The pdf Claude Code skill encodes that knowledge. It tells Claude which library to reach for based on what you’re trying to do, the correct patterns for each operation, and the specific pitfalls that aren’t covered in any README. The result is PDF-handling code that works correctly on the first attempt rather than after an afternoon of debugging.
What the pdf Skill Covers
The skill handles the full range of PDF operations across five broad categories:
Creating PDFs from scratch. Using reportlab or fpdf2 to generate documents programmatically — invoices, reports, certificates, labels. The skill covers page setup, font embedding, drawing primitives, and table layouts.
Filling PDF forms. Using pypdf or pdfrw to populate AcroForm fields in existing PDFs — the kind of task that sounds simple until you discover that field types, encodings, and font embedding each have their own failure modes. The skill handles these correctly.
Merging and splitting. Combining multiple PDFs into one, extracting specific pages, rotating pages, adding watermarks and page numbers to existing documents. pypdf is the right tool here; the skill specifies the correct API calls.
Extracting text and data. Using pdfplumber for text extraction and table detection from existing PDFs — including scanned documents that need OCR via pytesseract. The skill covers the pre-processing steps that make OCR reliable.
HTML-to-PDF conversion. Using weasyprint or pdfkit (wkhtmltopdf) to convert HTML/CSS to PDF — the right approach for complex layouts with CSS styling. The skill covers the dependency setup that trips people up on headless servers.
Example Workflow: Invoice Generation
A common real-world task: generating a PDF invoice from order data, with your company logo, itemised line items in a table, totals, and payment terms.
Generate a PDF invoice from order.json.
Include:
- Company logo in the top right (assets/logo.png)
- Invoice number, date, and due date in the header
- Itemised table with description, quantity, unit price, and line total
- Subtotal, VAT at 20%, and total at the bottom
- Payment terms paragraph at the foot
Save to output/invoice-{order_id}.pdfWith the pdf skill active, Claude knows to use reportlab for this (not fpdf2, which handles tables less cleanly), the correct approach for embedding the PNG logo without quality loss, and how to calculate column widths so the table renders correctly at A4 dimensions. The resulting script generates a professional invoice PDF that looks right without further adjustment.
Example Workflow: Extracting Data from PDFs
The other common scenario — going the other direction, extracting structured data from PDFs you’ve received:
Extract all invoice line items from the PDFs in /invoices.
Each PDF has a table with columns: Date, Description, Amount.
Output the combined data as a CSV at output/extracted.csv.
Some PDFs may be scanned — use OCR for those.The skill tells Claude to use pdfplumber for text-based PDFs and pytesseract for scanned ones, how to detect which is which, and the correct pre-processing steps (deskewing, contrast enhancement) that make OCR reliable on real-world scanned documents rather than clean test inputs.
Why Not Just Use pypdf for Everything?
This is the question the skill is specifically designed to answer. pypdf is excellent for merging, splitting, rotating, and basic text extraction. It’s the wrong choice for generating PDFs from scratch (use reportlab or fpdf2), for reliable table extraction from complex layouts (use pdfplumber), and for HTML-sourced documents (use weasyprint). Using pypdf to create a PDF from scratch leads to limited layout control and missing font embedding. The skill routes each task to the right library automatically.
Further Reading
- ReportLab User Guide
- pypdf documentation
- pdfplumber documentation
- Extend Claude with skills — Official Claude Code Docs
PDF handling is one of those areas where the gap between “technically possible” and “actually works correctly” is wider than it looks. The pdf skill closes that gap by giving Claude the specific library knowledge and pattern awareness to produce PDF code that’s correct on the first attempt — not after an afternoon of debugging font encoding and page geometry.
Leave a Reply
You must be logged in to post a comment.