pdf – Documents & Office skill for AI agents

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.
• Pick the interpreter with terminal. Use python when it already imports

the libraries (the Hermes Docker image ships them). Otherwise, when hermes

is on PATH, let Hermes build its shared, pinned documents environment under

the Hermes home: it survives container restarts, never touches the Hermes

install itself, and is safe to run from several agents at once. When it is

not (the terminal runs in a Docker sandbox, which has no Hermes), the block

builds a venv in the sandbox home with the same pinned versions. Use this

exact block in every document skill so they all share one environment:

  python -c "import pypdf, reportlab, pdfplumber" 2>/dev/null && PY=python || if command -v hermes >/dev/null 2>&1; then
    PY="$(hermes pm environment documents --extra documents --extra documents-pdf)"
  else
    PY="$HOME/.cache/hermes-docs-venv/bin/python"
    "$PY" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" 2>/dev/null || (
      # Safe to run from several agents at once: each caller builds a private venv,
      # a symlink publishes the first finished one atomically, the others delete theirs.
      mkdir -p "$HOME/.cache" && cd "$HOME/.cache" && stage="$(mktemp -d hermes-docs-venv.XXXXXX)" || exit 1
      old="$(readlink hermes-docs-venv)"  # an earlier build that no longer imports, if any
      python3 -m venv "$stage" &&
        "$stage/bin/python" -m pip install -q --disable-pip-version-check python-docx==1.2.0 openpyxl==3.1.5 python-pptx==1.0.2 reportlab==5.1.0 pypdf==6.21.2 pdfplumber==0.11.10 pypdfium2==5.14.0 &&
        "$stage/bin/python" -c "import docx, openpyxl, pptx, reportlab, pypdf, pdfplumber, pypdfium2" &&
        if [ -z "$old" ]; then python3 -c 'import os, sys; os.symlink(*sys.argv[1:])' "$stage" hermes-docs-venv
        elif [ "$(readlink hermes-docs-venv)" = "$old" ]; then
          ln -s "$stage" "$stage.lnk" && python3 -c 'import os, sys; os.replace(*sys.argv[1:])' "$stage.lnk" hermes-docs-venv &&
            case "$old" in hermes-docs-venv.??????) rm -rf "$old" ;; esac
        fi 2>/dev/null
      [ "$(readlink hermes-docs-venv)" = "$stage" ] || rm -rf "$stage" "$stage.lnk"
    )
  fi
  export PY
  "$PY" scripts/pdf_create.py --help
  

Run every helper below with "$PY". In PowerShell (Hermes runs on that

host, so it is on PATH):

$env:PY = hermes pm environment documents --extra documents --extra documents-pdf.

Never pip install into the interpreter that runs Hermes or into the

hermes pm environment one; Hermes owns both.

• Page rasterization (pdf_page_image.py, overlay rendering) uses pypdfium2, which the documents environment already has (if your python lacks it, switch PY to that environment with the command above), 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

| Task | Tool | Command / API |

|---|---|---|

| Create doc (headings, tables, images) | reportlab platypus | pdf_create.py spec.json -o out.pdf |

| Build fillable form | reportlab acroForm | pdf_make_form.py formspec.json -o form.pdf |

| Lint form layout / overlay image | pure python + PIL | pdf_form_layout.py formspec.json [--render-overlay o.png] |

| Per-page text | pdfplumber | pdf_read.py f.pdf --text |

| Tables → JSON/CSV | pdfplumber | pdf_read.py f.pdf --tables |

| Metadata / sizes / encrypted / scanned | pypdf + pdfplumber | pdf_read.py f.pdf --meta |

| Merge (+ outline) | pypdf | pdf_merge.py a.pdf b.pdf -o m.pdf |

| Split / extract / rotate | pypdf | pdf_split.py f.pdf --pages 2-5 --rotate 90 |

| List / fill / flatten form | pypdf | pdf_read.py --fields, pdf_fill_form.py |

| Encrypt / decrypt (AES-256) | pypdf | pdf_secure.py --encrypt/--decrypt |

| Watermark / stamp PDF page | pypdf | pdf_watermark.py f.pdf --stamp w.pdf |

| Stamp text/image at coordinates | reportlab + pypdf | pdf_stamp.py f.pdf --text "Sign here" --x 400 --y 60 |

| Pages → PNG (review / OCR hand-off) | pypdfium2 or pdftoppm | pdf_page_image.py f.pdf --pages 1-3 --out-dir imgs/ |

| Set/clear metadata, attachments | pypdf | pdf_meta.py --set-meta / --attach / --extract-attachments |

| Compress content streams | pypdf | pdf_split.py f.pdf --pages 1-N --compress |

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° step

… (full content is in the download package)