PDF

PDF Skill

Create PDFs from structured specs, build and fill AcroForm forms (with layout linting and visual overlays), extract text/tables/metadata, merge/split/rotate/watermark/stamp pages, export page images, manage metadata and attachments, and encrypt/decrypt — using pypdf, reportlab, and pdfplumber. Two absorbed capabilities live in references/ (read the matching file before those tasks):

• Scanned/image-only PDFs and OCR (pymupdf fast path, marker-pdf quality path, scripts/extract_pymupdf.py + scripts/extract_marker.py): references/ocr-extraction.md
• Editing text inside an existing PDF via natural-language prompts (nano-pdf CLI): references/nano-pdf-editing.md

When to Use

• Generate a report, invoice, or multi-page document as PDF.
• Build a fillable AcroForm (text/checkbox/radio/dropdown) from a JSON spec, linting the layout first.
• Pull text, tables (JSON/CSV), metadata, or form-field values out of a PDF.
• Merge, split, rotate, extract page subsets, watermark, stamp text/images at coordinates, bookmark, or compress PDFs.
• Export pages as PNGs for visual review or for OCR hand-off; set/clear document metadata; add/extract file attachments.
• Fill or flatten AcroForm forms; encrypt or decrypt with passwords.
• NOT for scanned/image-only PDFs (use references/ocr-extraction.md) and NOT for pixel-perfect HTML-to-PDF rendering (use a headless browser).

Prerequisites

• Python 3.10+ with pypdf, reportlab, pdfplumber: python -m pip install pypdf reportlab pdfplumber
• Optional, for page rasterization (pdf_page_image.py, overlay rendering): python -m pip install pypdfium2, or poppler's pdftoppm on PATH. Scripts fall back pypdfium2 → pdftoppm and report {"rendered": false, "missing": [...]} (exit 0) when neither exists.
• Each helper script checks imports lazily and prints an install hint if a dependency is missing.

How to Run

All helpers live in scripts/ and are argparse CLIs — run them with the terminal tool; every one supports --help. They read/write JSON strictly as UTF-8, print JSON results to stdout, and exit non-zero on failure.

python scripts/pdf_create.py spec.json -o out.pdf         # build PDF from JSON spec
python scripts/pdf_make_form.py formspec.json -o form.pdf # build fillable AcroForm from JSON spec
python scripts/pdf_form_layout.py formspec.json           # lint form layout BEFORE building
python scripts/pdf_form_layout.py formspec.json --render-overlay boxes.png [--pdf form.pdf]
python scripts/pdf_read.py doc.pdf --text                 # per-page text (JSON)
python scripts/pdf_read.py doc.pdf --tables --csv-dir t/  # tables to JSON + CSV files
python scripts/pdf_read.py doc.pdf --meta                 # metadata, page sizes, encrypted/scanned flags
python scripts/pdf_read.py form.pdf --fields              # form fields: name, type, value
python scripts/pdf_merge.py a.pdf b.pdf -o merged.pdf [--bookmarks]
python scripts/pdf_split.py doc.pdf --pages 1-3,7 -o part.pdf [--rotate 90]
python scripts/pdf_fill_form.py form.pdf --fields-json values.json -o filled.pdf [--flatten]
python scripts/pdf_secure.py doc.pdf --encrypt -o enc.pdf --user-password your-password
python scripts/pdf_secure.py enc.pdf --decrypt -o dec.pdf --password your-password
python scripts/pdf_watermark.py doc.pdf --stamp mark.pdf -o stamped.pdf [--under]
python scripts/pdf_stamp.py doc.pdf -o out.pdf --text "DRAFT" --x 150 --y 400 \
    --font-size 60 --rotation 45 --opacity 0.3 --color "#cc0000" [--pages 1-3]
python scripts/pdf_stamp.py doc.pdf -o out.pdf --image sig.png --x 400 --y 60 --width 120
python scripts/pdf_page_image.py doc.pdf --pages 1-3 --dpi 150 --out-dir imgs/
python scripts/pdf_meta.py doc.pdf --set-meta --title "T" --author "A" -o out.pdf
python scripts/pdf_meta.py doc.pdf --attach data.csv -o out.pdf
python scripts/pdf_meta.py doc.pdf --list-attachments | --extract-attachments dir/

Quick Reference

Procedure

1. Inspect first. Run pdf_read.py file.pdf --meta. Check encrypted (if true, decrypt first with pdf_secure.py --decrypt) and likely_scanned_pages. If pages are image-only, export them with pdf_page_image.py --pages <scanned> --dpi 300 --out-dir imgs/ and hand the PNGs to the references/ocr-extraction.md skill — do not report empty text as "no content".
2. Create. Write a JSON spec with write_file (elements: heading, paragraph, table, image, pagebreak; optional title/author metadata; page numbers are added automatically), then run pdf_create.py. Verify visually with vision_analyze on a rendered page image if layout matters.
3. Extract. --text gives a JSON list of per-page strings; --tables gives row arrays per page and can also emit CSV files. Read results with read_file; never eyeball a binary PDF directly.
4. Manipulate. pdf_merge.py concatenates and can add one bookmark per source file; pdf_split.py handles page ranges (1-based, e.g. 1-3,5,9-), rotation in 90° steps, and --compress. Watermark by preparing a single-page stamp PDF (e.g. via pdf_create.py) and overlaying it with pdf_watermark.py; for one-liner stamps ("sign here", diagonal DRAFT, corner labels) use pdf_stamp.py with text or an image at explicit coordinates.
5. Build forms. Write one form-spec JSON (fields with label_box/entry_box in PDF points — see references/forms.md), lint it with pdf_form_layout.py and fix every reported problem, optionally review the --render-overlay PNG with vision_analyze, then build with pdf_make_form.py and confirm with pdf_read.py --fields.
6. Fill forms. List fields (--fields) to learn exact names and types, write a UTF-8 JSON of {"FieldName": "value"} with write_file (checkboxes accept true/false; radio/choice values must match the field's export options), then pdf_fill_form.py. Re-read with --fields to confirm values landed.
7. Metadata & attachments. pdf_meta.py --set-meta writes Title/Author/Subject/Keywords (DocInfo); --clear-meta drops them; --attach/--list-attachments/--extract-attachments round-trip embedded files.
8. Secure. Encrypt with distinct user/owner passwords and AES-256. To remove a password you know, --decrypt writes an unencrypted copy.
9. Verify (see below) before reporting success.