pdf - SKILL.md Agent Skill

name: pdf description: Use this skill for PDF generation, conversion, inspection, extraction, editing, form filling, OCR, redaction, or render comparison. Triggers include requests to create a PDF, convert Markdown or HTML or LaTeX or DOCX or PPTX to PDF, extract text or tables or images, fill or inspect forms, OCR scans, compare revisions, or redact content. metadata: short-description: PDF workflows

PDF Skill

Use the repo-local toolkit under tools/pdfs/. The default operating loop is:

Render to images.
Inspect layout visually.
Perform the edit, extraction, or generation.
Re-render and verify.

Choose the right authoring path first

Even if the user wants a PDF deliverable, PDF is not always the right authoring format.

Text-heavy business docs: author in DOCX first, then convert with python3 tools/pdfs/scripts/lo_convert_to_pdf.py ...
Slide-like visual layouts: author in PPTX first, then export to PDF
Direct PDF generation or low-level edits: use this toolkit

If you are hand-tuning line breaks in a programmatically generated PDF, stop and reconsider whether DOCX or PPTX is the better source format.

Core loop

Render before and after any meaningful change:

python3 tools/pdfs/scripts/render_pdf.py input.pdf --out_dir /tmp/pdf-renders-in --dpi 200
python3 tools/pdfs/scripts/compare_renders.py before.pdf after.pdf --out_dir /tmp/pdf-diff --dpi 200

Rendered PNGs are the source of truth for layout QA. Do not trust extracted text alone for tables, forms, spacing, or clipping.

Common workflows

Inspect / extract

python3 tools/pdfs/scripts/pdf_inspect.py input.pdf
python3 tools/pdfs/scripts/pdf_extract.py text input.pdf --method pdfplumber
python3 tools/pdfs/scripts/pdf_extract.py tables input.pdf
python3 tools/pdfs/scripts/pdf_extract.py forms input.pdf --include_widgets

Edit / normalize

python3 tools/pdfs/scripts/pdf_edit.py paginate input.pdf -o output.pdf
python3 tools/pdfs/scripts/pdf_edit.py merge a.pdf b.pdf -o merged.pdf
python3 tools/pdfs/scripts/pdf_edit.py rotate input.pdf -o rotated.pdf --pages 1 --degrees 90
python3 tools/pdfs/scripts/pdf_preflight.py input.pdf

Redact / OCR

python3 tools/pdfs/scripts/pdf_redact.py text input.pdf redacted.pdf --text "secret" --ignore_case
python3 tools/pdfs/scripts/ocr_pdf.py scan.pdf -o searchable.pdf --force

Create / convert

python3 tools/pdfs/scripts/md_to_pdf.py input.md -o output.pdf
python3 tools/pdfs/scripts/html_to_pdf.py input.html -o output.pdf
python3 tools/pdfs/scripts/latex_to_pdf.py input.tex -o output.pdf
python3 tools/pdfs/scripts/lo_convert_to_pdf.py input.docx -o output.pdf

Forms

Best-effort Python path:

python3 tools/pdfs/scripts/pdf_edit.py fill-form in.pdf --values values.json -o out.pdf

If the form is stubborn, use the Node helpers:

bash tools/pdfs/js/install_deps.sh
node tools/pdfs/js/extract_form_fields.mjs --input in.pdf
node tools/pdfs/js/fill_form.mjs --input in.pdf --values values.json --output out.pdf --flatten

Quality bar for generated PDFs

No clipped text, overlaps, broken glyphs, or boundary-hugging table content
Verify visually after each material change
Prefer generous spacing and intentional column widths over dense layouts
Keep captions, tables, and figures visually paired
For tricky forms, verify in two renderers when possible

Load extra references only when needed

tools/pdfs/tasks/js_tools.md: Node helpers for forms and PDF.js extraction
tools/pdfs/tasks/forms_debugging.md: widget-level debugging workflow
tools/pdfs/troubleshooting/common.md: renderer and OCR troubleshooting
tools/pdfs/examples/smoke_test.md: runnable smoke flows

Toolkit map

tools/pdfs/scripts/render_pdf.py: render PDF pages to PNGs
tools/pdfs/scripts/compare_renders.py: render and diff two PDFs
tools/pdfs/scripts/pdf_inspect.py: metadata and structure overview
tools/pdfs/scripts/pdf_extract.py: text, tables, images, attachments, annotations, forms
tools/pdfs/scripts/pdf_edit.py: merge, split, rotate, crop, paginate, encrypt, optimize, fill-form
tools/pdfs/scripts/pdf_preflight.py: warnings and normalization hints
tools/pdfs/scripts/pdf_redact.py: true redaction
tools/pdfs/scripts/ocr_pdf.py: OCR wrapper
tools/pdfs/scripts/md_to_pdf.py: Markdown to PDF
tools/pdfs/scripts/html_to_pdf.py: HTML to PDF
tools/pdfs/scripts/latex_to_pdf.py: LaTeX to PDF
tools/pdfs/scripts/lo_convert_to_pdf.py: LibreOffice-based conversion
tools/pdfs/js/*.mjs: PDF.js and pdf-lib helpers

Final deliverable expectations

Keep only the final PDF in the requested output location unless the user asked for intermediates.
When the task is layout-sensitive, include a quick render verification pass before stopping.
Prefer ASCII - over typographic dashes in generated content when renderer compatibility is uncertain.