PDF Official

PDF skill

An Apache-2.0 toolkit for reading, composing, transforming, and filling PDF files. Written from scratch on top of permissively-licensed open-source libraries (pypdf, pdfplumber, pypdfium2, reportlab, pdf-lib, qpdf) so this can be embedded in commercial projects without special agreement.

Route the task

Pick the sub-guide by the verb of the request.

If a task mixes several of these, follow the order: probe → plan → extract or compose → validate.

Every path starts with a probe. scripts/survey.py returns page count, whether the file is encrypted, whether it has an AcroForm, and whether page 1 looks like a scan.

First install

Bundled runtime: when the MIMO_PYTHON environment variable is set, skip the installs below — run every command with python3/uv run replaced by "$MIMO_PYTHON" (pypdf/pypdfium2/reportlab/Pillow preinstalled; pip console scripts unavailable, use "$MIMO_PYTHON" -m <module>). A bundled qpdf is exposed as MIMO_QPDF (picked up automatically by the scripts here); invoke it directly as "$MIMO_QPDF" --check file.pdf.

Python-only path (all BSD / MIT / Apache) — covers 95% of tasks:

python3 -m pip install --upgrade pypdf pdfplumber pypdfium2 reportlab Pillow

Add these external binaries only when you actually need them:

# qpdf — merge/split/encrypt/repair, Apache-2.0
brew install qpdf                # macOS
apt-get install -y qpdf          # Debian / Ubuntu

# Tesseract — OCR for scanned PDFs, Apache-2.0
brew install tesseract
python3 -m pip install pytesseract pdf2image
apt-get install -y tesseract-ocr

# Poppler — pdftotext / pdftoppm / pdfimages, GPL-2.0
# Optional. Only install if you accept a GPL dependency at CLI level.
brew install poppler
apt-get install -y poppler-utils

Every script under scripts/ uses argparse. Exit codes: 0 OK · 1 runtime failure · 2 bad arguments · 3 validation failure (apply_values.py / overlay_text.py; sanity_check.py reports findings with exit 1). Any single script can be lifted into another project — none imports from a shared framework.

One-command triage

scripts/survey.py path/to/file.pdf --pretty

Sample output:

{
  "path": "/abs/path/file.pdf",
  "page_count": 12,
  "is_locked": false,
  "form_field_count": 34,
  "looks_scanned": false,
  "metadata": {"Title": "...", "Author": "...", "Producer": "..."}
}

Route by the flags:

• is_locked: true → unlock first (qpdf --password=… --decrypt). Almost every reader library refuses locked files.
• form_field_count > 0 → widgets path in interactive.md §1.
• form_field_count == 0 AND you need to fill it → overlay path in interactive.md §2.
• looks_scanned: true → skip pypdf text extraction, go straight to OCR (extract.md §5).

Which library for which task

Common gotchas

1. PDF origin is bottom-left, image origin is top-left. Every "off by a few points" bug is one of these two systems misapplied. Coordinate conversion is in one place: interactive.md §2.c.
2. pypdf.extract_text() returns nothing for scans. That's not a bug — there's no text stream. Use the looks_scanned flag and route to OCR.
3. Unicode subscripts / superscripts render as black rectangles in reportlab because Helvetica/Times/Courier don't ship those glyphs. Use <sub> / <super> XML in Paragraph, or move the pen manually on canvas. See compose.md §5.
4. CJK text renders as black boxes when the font never registered. reportlab does not consult the OS font system; a bad font name/path (思源黑体, PingFang, Noto on machines that lack it) plus a swallowed exception means a silent Helvetica fallback — and Helvetica has no CJK glyphs. Resolve fonts with the ladder in compose.md §4 (resolve_cjk_font()); the terminal fallback is the built-in CID font, never Helvetica.
5. XFA forms are not AcroForms. If probe_fields.py returns [] on a PDF that clearly has widgets in Adobe Reader, it's XFA — flatten it in Acrobat first.
6. writer.encrypt(pw) in pypdf uses RC4 by default. For real AES-256, pass algorithm="AES-256", or use qpdf --encrypt … 256 --.

What's next

Open the sub-guide from the routing table and work through it end to end. Each sub-guide has a Validation section at the bottom describing how to confirm the result.