---
name: pdf
description: Use for all PDF tasks—generate formatted PDF reports and documents from scratch, extract text/tables/images, merge/split/rotate pages, add watermarks, fill AcroForm fields, encrypt/decrypt, OCR scanned pages, inspect form structure, and rasterize pages. Invoke when the user mentions .pdf files, wants a PDF report, or needs PDF output of any kind.
user-invocable: true
---

# PDF skill

Use the **Skill** tool with `action=run_script` and paths relative to this skill, e.g.
`Skill(skill_name="pdf", action="run_script", script="scripts/md_export_from_pdf.py", args="input.pdf out.md")`.

## Must-read guides (load with `read_file`)

Load the relevant guide before starting — they contain decision logic and JSON shapes the scripts expect.

| File | When |
|------|------|
| [`generation_workflows.md`](generation_workflows.md) | **Creating a new PDF** — reports, invoices, formatted documents (reportlab, weasyprint, fpdf2). |
| [`form_workflows.md`](form_workflows.md) | Filling an existing PDF — AcroForm fields or annotation overlay (order of scripts, JSON shapes). |
| [`advanced_reference.md`](advanced_reference.md) | Extra tooling — pdf-lib (JS), PDF.js, Poppler CLI, qpdf, OCR, table extraction. |

## Decision tree

```
Need to CREATE a new PDF?        → generation_workflows.md
Need to FILL an existing PDF?    → form_workflows.md → scan_fillable_pdf.py first
Need to EXTRACT text / analyze?  → md_export_from_pdf.py or form_schema_dump.py
Need to EXTRACT TABLES?          → extract_tables_from_pdf.py
Need to EXTRACT IMAGES?          → extract_images_from_pdf.py
Need OCR on scanned pages?       → ocr_pdf.py
Need to MERGE PDFs?              → merge_pdfs.py
Need to SPLIT pages?             → burst_pdf_pages.py
Need to ROTATE pages?            → rotate_pdf_pages.py
Need to add a WATERMARK?         → watermark_pdf.py
Need to ENCRYPT a PDF?           → encrypt_pdf.py
Need to DECRYPT a PDF?           → decrypt_pdf.py
Need to RASTERIZE pages?         → pdf_page_png_export.py
```

## Scripts (in `scripts/`)

| Script | Role |
|--------|------|
| `md_export_from_pdf.py` | Extract text per page to Markdown (pdfplumber). |
| `burst_pdf_pages.py` | Split one PDF into single-page PDFs (pypdf). |
| `merge_pdfs.py` | Combine multiple PDFs into one (pypdf). |
| `rotate_pdf_pages.py` | Rotate specified pages by 90/180/270° (pypdf). |
| `watermark_pdf.py` | Add diagonal text watermark to all pages (pypdf + reportlab). |
| `encrypt_pdf.py` | Encrypt a PDF with AES-256 password (pypdf). |
| `decrypt_pdf.py` | Decrypt a password-protected PDF (pypdf). |
| `extract_images_from_pdf.py` | Extract embedded images to PNG (pypdf + Pillow). |
| `extract_tables_from_pdf.py` | Extract tables to CSV or JSON (pdfplumber). |
| `ocr_pdf.py` | OCR scanned pages to Markdown (pdf2image + pytesseract). |
| `list_form_fields.py` | JSON metadata for AcroForm fields. |
| `write_acroform_fields.py` | Fill AcroForm fields from JSON. |
| `overlay_widget_values.py` | Fill flat PDFs using FreeText annotation overlay. |
| `scan_fillable_pdf.py` | Quick check for fillable AcroForm fields. |
| `bbox_self_check.py` | Validate label/entry box geometry from JSON. |
| `form_schema_dump.py` | Dump form-oriented structure — labels, lines, checkboxes (pdfplumber). |
| `pdf_page_png_export.py` | Rasterize pages to PNG (pdf2image / Poppler). |
| `debug_highlight_render.py` | Draw validation bounding boxes on an image (Pillow). |

## Python patterns

**Creating PDFs:** Use `reportlab` (precise layout), `weasyprint` (HTML → PDF), or `fpdf2` (simple docs). See `generation_workflows.md`.

**Merge / split / rotate:** Use `pypdf` (`PdfReader` / `PdfWriter`) for inline scripting, or use the dedicated scripts above.

## Dependencies

`pdfplumber`, `pypdf`, `pdf2image` (+ Poppler on PATH), `Pillow`, `reportlab` or `weasyprint` or `fpdf2` for generation, `pytesseract` (+ Tesseract binary on PATH) for OCR. See `requirements.txt`.
