# PDF Generation in Skills

When a skill needs to produce a PDF, the output is always a two-stage process: the skill authors the HTML, and the agent renders it to PDF with the on-device `browser-pdf-save` tool.

## The rule

Never instruct the agent to write or execute raw Node.js scripts (e.g. `require('playwright')`, `page.pdf()`, `npx playwright`). Playwright is not on device — these scripts fail with MODULE_NOT_FOUND, waste tool calls searching the filesystem, and produce hardcoded paths that break on reinstall.

Instead, skills that produce PDFs should:

1. **Build the HTML** — the skill's behaviour section describes what the document contains and how it's structured. The agent writes the HTML file using standard file tools.
2. **Render with `browser-pdf-save`** — serve the HTML over `http://127.0.0.1:<port>`, `browser-navigate` to it, then `browser-pdf-save` to the output path. The tool drives the device's Chromium over CDP (honours `@page`/print CSS, prints backgrounds); no Playwright is involved.

## Print-ready HTML constraints

HTML intended for PDF output must follow print-ready layout patterns. The most common failures when agents design their own pagination are rigid fixed-height page divs (causing whitespace gaps) and `position: fixed` hacks for headers/footers (causing overlap and duplication).

**Continuous flow layout** — content flows naturally. Use `@page` margin rules for page margins, not wrapper divs with fixed heights. Use `page-break-inside: avoid` on logical units (cards, tables, stat groups) and `page-break-before: always` on major section dividers.

**Page numbers and running footers** — use `@page` margin boxes (`@bottom-center { content: counter(page); }`), not JavaScript or position-fixed elements.

**Dark backgrounds in print** — browsers strip background colours by default. Add `print-color-adjust: exact; -webkit-print-color-adjust: exact;` to dark elements in `@media print`.

**Cover and back pages** — full-bleed pages use `height: 100vh; page-break-after: always;` in `@media print` with zero `@page` margins (via `@page :first` for covers, named pages for back pages).

**Glassmorphism and backdrop-filter** — these do not survive browser print rendering. Any section using glassmorphism needs a pre-rendered PNG fallback image that is hidden on screen and shown only in `@media print`.

## What the skill file should contain

The skill's SKILL.md describes the document's purpose and structure. A `references/` file holds the HTML template or content specification. The skill should state that PDF rendering goes through `browser-pdf-save` — it should not contain Playwright code, npm commands, or file path assumptions about any Playwright installation.