Pdf

pdf skill

Purpose: Give the agent a small, deterministic set of CLIs for the common PDF operations: render Markdown to a well-typeset PDF, merge PDFs, split them by page range or into individual pages, and (via references) extract text or fill forms. Picking the right library on the fly is the single biggest source of PDF bugs; delegating to scripts that embed those choices removes the variance.

1. Red Flags (Anti-Rationalization)

STOP and READ THIS if you are thinking:

• "I'll use pypdf to extract the text." → WRONG for layout-dependent content. pypdf's text extraction is famously unreliable on anything with columns or complex layout; use pdfplumber. See [references/library-selection.md](references/library-selection.md).
• "I'll improvise a pdfplumber script to convert this PDF to Markdown." → WRONG to improvise from scratch. Run pdf_extract.py for the structured dump and follow [references/pdf-to-markdown.md](references/pdf-to-markdown.md) — and never skip the scan check: on a scanned PDF pdfplumber returns empty text silently; pdf_extract.py exits 10 instead.
• "I'll reach for playwright for Markdown → PDF because it handles everything." → WRONG. Playwright pulls a 200 MB Chromium install. weasyprint handles 95% of Markdown/HTML inputs with a fraction of the footprint.
• "I'll fill this XFA form with pypdf." → WRONG. pypdf doesn't fill XFA — only AcroForm. Detect the form type first (see [references/forms.md](references/forms.md)) and fail loudly if it's XFA rather than silently writing an unchanged file.
• "I'll skip checking exit codes from pdf_merge.py." → WRONG. Missing an input file produces exit 1 and the output is absent — silently assuming success ships a broken deliverable.

2. Capabilities

• Render Markdown (+ optional custom CSS) to a typeset PDF via weasyprint. Fenced ``mermaid blocks pre-render to PNG via mmdc; bundled scripts/mermaid-config.json ships an office-friendly Cyrillic-capable font stack (override with --mermaid-config PATH, opt out with --no-mermaid-config). Inline $…$ and display $$…$$ **math** pre-render to MathML via the bundled katex (weasyprint typesets MathML natively; it runs no JS, so client-side KaTeX/MathJax can't be used) — currency ($5) and $ inside code/fences are left untouched, and without node/KaTeX formulas degrade to literal text (opt out with --no-math, fail-hard with --strict-math). The PDF carries a navigable **outline (bookmarks)** auto-built from h1–h6` headings — no flag needed.
• Render HTML / web archives to PDF via html2pdf.py — same weasyprint pipeline, natively handles .html/.htm, .mhtml/.mht, and .webarchive. Validated across Fern (OpenRouter), Mintlify (Anthropic Claude Code, Discord, Berachain), GitBook (Hyperliquid), Confluence (Atlassian wikis), Хабр, vc.ru and generic blogs — 34/34 fixtures pass in both modes. Bundled stylesheet on by default; --no-default-css for fully-styled inputs (BI dashboards, branded reports); --css EXTRA.css stacks on top. --reader-mode extracts the main article body (Safari Reader View parity). --timeout 180 SIGALRM watchdog with $HTML2PDF_TIMEOUT override. Universal preprocessing handles draw.io/Confluence SVG diagrams, table-based code blocks (Fern/Mintlify shiki), Tailwind/FontAwesome icon strip, ARIA-role tables (GitBook), ad-network removal, and pathological-CSS protection (Хабр content-drop bug, vc.ru CPU-loop bug). Full pipeline + flag semantics + per-platform notes documented in [references/html-conversion.md](references/html-conversion.md). Output PDFs carry a navigable outline (bookmarks) from h1–h6 headings — engine-agnostic (weasyprint and --engine chrome; the chrome engine emits a tagged PDF, the mechanism Chromium uses for the outline).
• Merge multiple PDFs into one preserving bookmarks (pdf_merge.py).
• Split a PDF by explicit page ranges, one-per-page, or fixed-size chunks (pdf_split.py).
• Stamp a text or image watermark on every (or selected) page via pdf_watermark.py (drafts, "CONFIDENTIAL", brand stamps). --position center|top-left|top-right|bottom-left|bottom-right|diagonal, --opacity, --rotation, --pages "1-5,8". Builds one overlay per unique page mediabox, so heterogeneous decks (Letter+A4) keep correct proportions.
• Detect, inspect, and fill AcroForm fields via pdf_fill_form.py — three modes: --check (form-type triage with exit codes 0/11/12 = AcroForm/XFA/none), --extract-fields (dump field schema as JSON for editing), and fill mode (INPUT.pdf DATA.json -o OUT.pdf [--flatten]). XFA forms are detected and refused with a clear message.
• Extract text, tables, and layout via pdfplumber (documented; inline usage from the agent is fine).
• Dump a PDF's per-page text + tables to structured JSON via pdf_extract.py — a structured dump, NOT a Markdown converter (it never emits Markdown). Its defining feature is scan detection: an image-only document exits 10 with a DocumentScanned signal instead of silently yielding empty text. Robust word-splitting by default: LaTeX/academic two-column PDFs encode inter-word spacing as positional gaps (no space glyphs), which pdfplumber's absolute tolerance glues into ASurveyonBlockchain; a font-relative x_tolerance_ratio (default 0.15) splits them correctly without regressing real-space PDFs (tune/disable via --x-tolerance-ratio R, see [references/pdf-to-markdown.md §3.8](references/pdf-to-markdown.md)). Pairs with [references/pdf-to-markdown.md](references/pdf-to-markdown.md) for the PDF→Markdown decision tree and recipe; final Markdown composition stays agent judgement.
• OCR a scanned (image-only) PDF into a searchable PDF via pdf_ocr.py — wraps ocrmypdf to overlay an invisible OCR text layer (default languages eng+rus), the remediation hop for pdf_extract.py exit 10. The OCR engine is soft-optional: install with bash scripts/install.sh --with-ocr (+ system tesseract/eng/rus/ghostscript); a missing engine or language pack fails loud, never silent. See [references/ocr.md](references/ocr.md).
• Render any .pdf (or peer-skill .docx/.xlsx/.pptx) into a single PNG-grid preview via preview.py (uses Poppler directly for .pdf; LibreOffice + Poppler for OOXML).
• Emit failures as machine-readable JSON to stderr with --json-errors (uniform across all four office skills).

3. Execution Mode

• Mode: script-first for the bundled operations, prompt-first with library references for extraction and form filling.
• Why this mode: The bundled operations (render, merge, split) are stable recipes. Extraction and form filling depend heavily on the specific document and deserve inspection before running — the references guide the inline work.
• pdf_extract.py — the bounded exception: extracting per-page text + tables to a JSON dump IS a stable recipe, so it is bundled (it also closes the silent-scan failure with code). Markdown composition — heading levels, reading order, table stitching — stays prompt-first agent judgement: there is no Markdown-converter script, by design. See [references/pdf-to-markdown.md](references/pdf-to-markdown.md).

4. Script Contract

• Commands:
• python3 scripts/md2pdf.py INPUT.md OUTPUT.pdf [--page-size letter|a4|legal] [--css EXTRA.css] [--base-url DIR] [--no-mermaid] [--strict-mermaid] [--mermaid-config PATH | --no-mermaid-config] [--no-math] [--strict-math]
• python3 scripts/html2pdf.py INPUT OUTPUT.pdf [--page-size letter|a4|legal] [--css EXTRA.css] [--base-url DIR] [--no-default-css] [--reader-mode] [--archive-frame N|main|all|auto] [--list-frames] [--timeout SECONDS] [--engine weasyprint|chrome] [--chrome-js] — INPUT may be .html/.htm, .mhtml/.mht, or .webarchive; sub-resources in archives are extracted to a temp dir automatically. --reader-mode extracts the main article content (Confluence-priority candidate list with body-ratio guard for `; longest-match per selector handles archive pages with multiple .entry divs and Disqus comment threads + title-match LCS bonus for multi-article feed pages), stripping navigation, ads, sidebars, and SPA chrome (ARIA role=navigation\|complementary\|banner\|contentinfo + semantic // + shallow ) — ideal for browser-saved news/blog/docs pages and hydrated SPAs. **--archive-frame N|main|all|auto (pdf-8, 2026-05-05)**: selects which inner frame in webarchive/MHTML to render — main (default) = main resource only; N (1-indexed) = specific inner frame; all = concat all "substantial" frames (≥ 1 KB + 0 + ≥ 30 chars text + not single--only) with Frame N separators + per-frame namespace + sha1 image-dedup + encoding parity; auto = deterministic (0 substantial → main, 1 → that frame with main-dominance guard, 2+ → all). Vendor-agnostic: validated on 9 real fixtures across Angular/Closure/Framer/bare-DOM SPA stacks without a single vendor name in the heuristic. **--list-frames (pdf-8)**: prints inner-frame inventory (index/kind/substantial/bytes/scripts/text-len/url) and exits without rendering — for picking N deterministically. --timeout (default 180s, $HTML2PDFTIMEOUT env, 0 disables) caps weasyprint render via signal.SIGALRM for pathological inputs. Exit 1 with RenderTimeout envelope on watchdog fire; exit 2 with NoSubstantialFrames / FrameIndexOutOfRange envelopes for archive-frame errors. **--engine weasyprint|chrome (pdf-11, 2026-05-05)**: render engine selector. weasyprint (default) — pure-Python typeset PDF, no browser runtime. chrome — opt-in headless Chromium via Playwright (~150 MB, install with bash install.sh --with-chrome). Use chrome when weasyprint produces broken output: Material 3 calc/var bugs (Gmail-class), Framer infinite layout loops, ELMA365 inline.py assertion, JS-hydrated content, charts. Chrome path skips weasyprint preprocess (calc-strip, font-face-strip, NORMALIZE_CSS) — those are weasyprint workarounds Chrome doesn't need; reader-mode and --css EXTRA.css remain engine-agnostic. **Chrome render hardenings (universal layout strategy, post-VDD-iter-8 — 8 adversarial iterations)**: strip from HTML + JS-enabled at context level (page can't run own JS → no Gmail self-destruct, no Angular half-hydration; we keep page.evaluate for surgical DOM normalization; --chrome-js opts page-JS back in for canvas/hydration); stripped (webarchives carry which would route every relative URL to the offline-blocked origin); media forced to screen (default print triggers nav-hiding @media print rules in SPAs); 1280×1024 viewport (desktop CSS); layout-normalize CSS — high-specificity body release, icon-font ligature suppression with :not(:has(*)) leaf-only guard (avoids font-size:0 cascading through CSS inheritance to children), [class~="spinner"] exact-word match (not substring — avoids hiding class="spinner-class-banner" and similar), image cap (200px), avatar-image cap (48×48 only on ... img, not bare class so containers aren't shrunk); JS-based DOM normalize via page.evaluate — width-gate offsetWidth ≥ 200 for overflow release (narrow icon-sidebars at 64px stay clipped, no label leak), substantial-modal release (position:fixed → static only when wide AND tall AND text-rich), modal-portal hide (when modal released, hide non-portal body children to remove underlying CRM page); **scale-to-fit page.pdf(scale = pdfusable / viewport_width) ≈ 0.561** so 1280 px layout fits A4's ~718 px usable width without right-edge cutoff. Validated on 3 SPA archive shapes × 2 modes (Gmail Closure email, ELMA365 Angular dashboard, Yandex Cloud Console marketplace) — all 6 combinations produce full content with no overlap, no cutoff, no chrome-icon ligatures, no underlying-page noise. **Recommended composition**: --engine chrome --reader-mode for email/newsletter/article archives (cleaner article-only render); --engine chrome alone for dashboards/registries/structured UIs (preserves card layout). Exit 1 with ChromeEngineUnavailable` envelope if Playwright not installed.
• python3 scripts/pdf_merge.py OUTPUT.pdf INPUT1.pdf INPUT2.pdf [INPUT3.pdf ...]
• python3 scripts/pdf_split.py INPUT.pdf --ranges "1-5:part1.pdf,6-10:part2.pdf"
• python3 scripts/pdf_split.py INPUT.pdf --each-page OUTDIR/
• python3 scripts/pdf_split.py INPUT.pdf --every N OUTDIR/
• python3 scripts/pdf_watermark.py INPUT.pdf OUTPUT.pdf (--text "DRAFT" | --image STAMP.png) [--opacity 0.3] [--position center|top-left|top-right|bottom-left|bottom-right|diagonal] [--rotation 45] [--font-size 60] [--color "#888"] [--scale 0.5] [--pages "all"|"1-5,8,12-end"]
• python3 scripts/pdf_fill_form.py --check INPUT.pdf — exit 0/11/12 = AcroForm/XFA/none. (Custom codes start at 10 to leave 0–9 for argparse / shell convention.)
• python3 scripts/pdf_fill_form.py --extract-fields INPUT.pdf -o fields.json
• python3 scripts/pdf_fill_form.py INPUT.pdf DATA.json -o OUTPUT.pdf [--flatten]
• python3 scripts/preview.py INPUT OUTPUT.jpg [--cols 3] [--dpi 110] [--gap 12] [--padding 24] [--label-font-size 14] [--soffice-timeout 240] [--pdftoppm-timeout 60]
• python3 scripts/pdf_extract.py INPUT.pdf [-o OUT.json] [--layout] [--password PW] [--x-tolerance-ratio R] [--json-errors] — dumps per-page text + tables as structured JSON (NOT Markdown). --x-tolerance-ratio (default 0.15) is the font-relative word-split threshold that un-glues LaTeX/academic PDFs; 0 disables it (legacy absolute tolerance). Exit codes: 0 success; 1 failure (missing / not-a-PDF / corrupt / encrypted-without-password); 2 usage error; 6 SelfOverwriteRefused (-o resolves to the input PDF); 10 DocumentScanned — the whole document is image-only, run OCR or read the pages as images. On exit 10 the dump is still emitted; exit 10 + stderr is the loud signal. Default output is stdout; -o writes a file (idempotent). See [references/pdf-to-markdown.md](references/pdf-to-markdown.md).
• python3 scripts/pdf_ocr.py INPUT.pdf OUTPUT.pdf [--lang eng+rus] [--skip-text|--redo-ocr|--force-ocr] [--sidecar OUT.txt] [--jobs N] [--password PW] [--deskew] [--rotate-pages] [--clean] [--json-errors] — OCR a scanned PDF into a searchable PDF via ocrmypdf (default languages eng+rus). --password decrypts an encrypted input; --rotate-pages needs tesseract osd data; --clean needs unpaper. Exit codes: 0 success; 1 failure (type in the envelope: OcrEngineUnavailable / LanguagePackMissing / EncryptedInput / InputUnreadable / PriorOcrFound / OutputWriteFailed / InputNotFound); 2 usage; 6 SelfOverwriteRefused. Soft-optional engine — bash scripts/install.sh --with-ocr first. See [references/ocr.md](references/ocr.md).
• All scripts above accept --json-errors to emit failures as a single line of JSON on stderr ({v, error, code, type?, details?}). The schema version v is currently 1; argparse usage errors are routed through the same envelope (type:"UsageError").
• Inputs: positional paths; optional flags per command.
• Outputs: single PDF files (md2pdf, pdf_merge) or multiple PDFs under a directory (pdf_split). All stdout goes to the output path list.
• Failure semantics: non-zero exit on missing inputs, invalid range specs, or library errors. Error detail to stderr.
• Idempotency: all three scripts overwrite their outputs on re-run.
• Dry-run support: not applicable.

5. Safety Boundaries

• Allowed scope: only paths named on the command line.
• Default exclusions: do not fetch remote resources unless the user explicitly provides URLs; md2pdf.py --base-url defaults to the input's directory.
• Destructive actions: all three scripts overwrite their outputs without prompting.
• Optional artifacts: custom CSS via md2pdf.py --css is optional; defaults produce a reasonable layout.

6. Validation Evide

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MatrixFounder
• Source: MatrixFounder/Universal-skills
• License: Apache-2.0

Install and usage instructions live in the source repository linked above.