Document PDF

Document PDF Skill — Quick Reference

This skill enables PDF creation, extraction, manipulation, and analysis. Apply these patterns when users need to generate invoices, reports, extract data from PDFs, merge documents, or work with PDF forms.

Modern Best Practices (Jul 2026):

• PDF is a release artifact, not the editable source of truth.
• Validate export fidelity (fonts, images, links) and accessibility where required.
• Accessibility: if compliance matters, target a tagged/structured PDF workflow (often PDF/UA-aligned) and validate with tooling.
• EU distribution: EAA (June 2025) typically implies EN 301 549 expectations for customer-facing PDFs.
• Treat PDFs as sensitive: scrub metadata at all layers (PDF-internal, filesystem, OS xattrs), ensure real redaction, and control distribution.
• Metadata exists in multiple layers: PDF Info/XMP (internal), filesystem dates (OS), and extended attributes (macOS quarantine, provenance). Scrubbing one layer while ignoring others leaves traces.

Core Decision Rules (2026)

• First decide: born-digital PDF (selectable text) vs scanned PDF (images). Scanned PDFs usually require OCR; see references/pdf-extraction-patterns.md.
• If the user needs accessibility/compliance, prefer generating from a source format that supports structure (DOCX/HTML + proper export) rather than “post-fixing” an untagged PDF.
• For deterministic ops (merge/split/rotate/scrub), prefer scripts/ helpers over re-implementing ad hoc.
• Never treat black rectangles or overlays as redaction; use real redaction and verify by copy/paste + search.
• Table extraction is probabilistic, not deterministic: run pdfplumber first and spot-check output against the source page; escalate to Camelot only when columns/rows are visibly wrong, and always inspect Camelot's per-table accuracy score rather than trusting output blindly.
• PyMuPDF/fitz (used by scrub_metadata.py and most redaction/OCR-prep code below) is dual-licensed AGPL-3.0 / commercial. Flag this before shipping it inside a closed-source product or SaaS backend — AGPL's network-use clause can trigger a source-disclosure obligation; get a commercial license from Artifex or substitute pypdf/pdfplumber where the required functionality overlaps.
• pdf-lib (Node) has had no active upstream releases for an extended period as of mid-2026; for new Node projects needing ongoing fixes, evaluate a maintained fork (e.g. @cantoo/pdf-lib) before committing, and pin the dependency either way.

Quick Reference

When to Use This Skill

Use this skill when a user requests:

• Generate PDFs from data (invoices, reports, certificates)
• Extract text or tables from existing PDFs
• Merge multiple PDFs into one document
• Split PDFs into separate files
• Fill PDF forms programmatically
• Add watermarks, headers, footers
• Convert HTML/web pages to PDF

Default Workflow

• Create: use Playwright for browser-faithful HTML/CSS, WeasyPrint for semantic/tagged HTML exports, ReportLab for Python-heavy layouts, or pdfkit for Node-first custom layout.
• Extract: first classify the file as born-digital vs scanned; run OCRmyPDF before downstream extraction on scanned PDFs, then use references/pdf-extraction-patterns.md.
• Ship: run assets/pdf-release-checklist.md; add PAC / Acrobat checks for accessibility-sensitive PDFs and veraPDF when archival conformance matters.

ASCII Flow

PDF request
  |
  v
Classify task
  |-- create new PDF
  |-- extract text / tables / images
  |-- modify existing PDF
  |-- fill / sign forms
  |-- merge / split / rotate / scrub
  |
  v
Classify source and risk
  |-- born-digital ----> extract directly
  |-- scanned ---------> OCR first
  |-- sensitive -------> real redaction + metadata scrub
  |-- compliance ------> tagged / structured source workflow
  |
  v
Select tool or script
  |-- HTML/CSS --------> Playwright or WeasyPrint
  |-- Python layout ---> ReportLab / FPDF2
  |-- deterministic ---> scripts/ + pypdf
  |-- extraction ------> pdfplumber / OCRmyPDF / Camelot
  |
  v
Verify fidelity, accessibility, metadata, and redaction

Scripts (Deterministic Operations)

Scripts are optional helpers; they assume Python 3 plus the listed dependencies in each file.

• Merge: python3 scripts/merge_pdfs.py merged.pdf a.pdf b.pdf
• Split: python3 scripts/split_pdf.py in.pdf out_dir --each-page
• Rotate: python3 scripts/rotate_pdf.py in.pdf out.pdf --degrees 90
• Scrub metadata and active content: python3 scripts/scrub_metadata.py in.pdf out.pdf
• Scrub with filesystem + xattr cleanup: python3 scripts/scrub_metadata.py in.pdf out.pdf --filesystem-date 2025-09-20 --strip-xattrs

PDF Structure Patterns

Invoice Template

INVOICE STRUCTURE
├── Header (logo, company info, invoice #)
├── Bill To / Ship To blocks
├── Line items table
│   ├── Description | Qty | Unit Price | Total
│   └── Subtotal, Tax, Total
├── Payment terms
└── Footer (contact, thank you)

Report Template

REPORT PDF STRUCTURE
├── Cover page (title, author, date)
├── Table of contents
├── Body sections with page numbers
├── Charts/images with captions
├── Appendices
└── Running header/footer

Decision Tree

PDF Task: [What do you need?]
    ├─ Create new PDF?
    │   ├─ Browser-faithful HTML/CSS → Playwright
    │   ├─ Semantic HTML / tagged export → WeasyPrint
    │   ├─ Node-first custom layout → pdfkit
    │   └─ Python complex layout → ReportLab / FPDF2
    │
    ├─ Extract from PDF?
    │   ├─ Born-digital text → pdfplumber (Python)
    │   ├─ Scanned pages → OCRmyPDF, then pdfplumber
    │   ├─ Tables → pdfplumber first, Camelot for hard cases
    │   └─ Images / raster work → PyMuPDF/fitz
    │
    ├─ Modify existing PDF?
    │   ├─ Add text/images → pdf-lib (Node)
    │   ├─ Merge/split/rotate/scrub → pypdf + scripts
    │   ├─ Fill forms → pdf-lib
    │   └─ Sign → pyHanko
    │
    └─ Batch processing?
        └─ OCRmyPDF / pypdf / pdfplumber pipeline

Do / Avoid (Jul 2026)

Do

• Keep a versioned source document (doc/slide/design file) alongside the PDF.
• Verify links and reading order for long documents.