Structured `.pdf` operations: extract text/tables, merge pages from multiple PDFs, split a PDF by page ranges, fill PDF form fields, and generate fresh PDFs from JSON. Trigger when the user wants programmatic PDF work without natural-language rewriting — examples: pull tables from a report, combine three PDFs, extract pages 5-12, fill a tax form, or build a new PDF from data. Distinct from `nano-pdf`, which uses an LLM to rewrite a page from a sentence; this skill is deterministic byte-level work via pypdf, pdfplumber, and reportlab.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
Structured `.pdf` operations: extract text/tables, merge pages from multiple PDFs, split a PDF by page ranges, fill PDF form fields, and generate fresh PDFs from JSON. Trigger when the user wants programmatic PDF work without natural-language rewriting — examples: pull tables from a report, combine three PDFs, extract pages 5-12, fill a tax form, or build a new PDF from data. Distinct from `nano-pdf`, which uses an LLM to rewrite a page from a sentence; this skill is deterministic byte-level work via pypdf, pdfplumber, and reportlab.
Deterministic, structural PDF operations. Use this skill for programmatic
work where you know exactly what you want done. Use the sibling nano-pdf
skill instead when the task is "rewrite this page to say X" — nano-pdf
applies a natural-language edit; pdf-toolkit applies an explicit operation.
Text uses pdfplumber (already in default dependencies) which preserves
column layout better than naive PDF text extraction. Tables use
pdfplumber.extract_tables() with default settings; for tricky layouts
pass --tables-strategy lines|text|explicit to switch detection mode.
For OCR (scanned PDFs), this skill does not include Tesseract — use the
sibling skill that wraps an OCR engine (out of scope here).
The script discovers fields via pypdf.PdfReader.get_fields() and updates
them with update_page_form_field_values(). Fields not present in the JSON
are left untouched. Run with --list-fields to enumerate the form's fields
without filling.
Caveats:
/Btn checkbox fields take the export value (often Yes, On, or 1)
rather than true — inspect with --list-fields to discover.
AcroForm fills only. XFA forms (used by some legal templates) require
Adobe-specific tooling and are out of scope.
Some signed PDFs invalidate the signature when fields change. Strip
signatures explicitly with --clear-signatures if that is intended.
Path D: Generate from scratch
Use reportlab directly when you need a new PDF:
from reportlab.pdfgen import canvas
from reportlab.lib.pagesizes import LETTER
from pathlib import Path
c = canvas.Canvas(str(Path("out.pdf")), pagesize=LETTER)
c.setFont("Helvetica-Bold", 18)
c.drawString(72, 720, "Q3 Review")
c.setFont("Helvetica", 11)
c.drawString(72, 696, "Revenue grew 18% year over year.")
c.showPage()
c.save()
For tables, headers/footers, and multi-column layouts, switch to
reportlab.platypus (SimpleDocTemplate, Paragraph, Table,
PageBreak). See references/reportlab.md.
Boundary with nano-pdf
nano-pdf (sibling bundled skill) wraps an LLM that takes a page index and
a natural-language instruction. Use it when the change is "fix the typo on
page 1" or "make the title shorter". Use this skill when the change is
"merge these three PDFs", "extract the tables", or "fill the form". The two
do not overlap: if you find yourself reaching for nano-pdf to do a merge,
switch to pdf-toolkit; if you reach here to "rewrite page 5 to be friendlier",
switch back.
Common pitfalls
Symptom
Cause
Fix
Extracted text is empty
Scanned PDF, no text layer
OCR is out of scope; use a separate OCR skill
Garbled characters in extract
PDF uses a custom font encoding
Try pdfplumber.open(path, laparams={...}) with char_margin adjustments
Merged PDF is huge
Underlying PDFs include large embedded fonts
Subset fonts via pypdfcompress_content_streams()
Form fill silently no-ops
Field name in JSON does not match PDF field name
Run with --list-fields first to see exact names
Pages out of order after split
Range overlap collapsed unexpectedly
Use disjoint ranges, e.g. 1-3,4-6 not 1-5,3-6
Boundaries
This skill works with text-based and form-based PDFs. Scanned image PDFs
need OCR before any text path produces results.
Encrypted PDFs are read-only here. Decryption requires the user-supplied
password and is out of scope for this skill.
For PDF-to-image rendering, use a separate skill that wraps Poppler or
PyMuPDF.
Digital signature operations (signing, verifying, revoking) are out of
scope.
