PDF

Table of contents

1. How it works with an AI agent

User: "Write a client-ready Q3 strategy proposal as a
       polished PDF, our brand is steel blue"
  |
  v
AI Agent (CoDev Code / OpenCode / Claude Code / Codex / Cursor / ...)
  | 1. Sees trigger signals (PDF, report, proposal, resume,
  |    professional document, fill the form...) -> loads SKILL.md
  | 2. Routes the task: CREATE (new), FILL (form fields) or
  |    REFORMAT (existing doc -> styled PDF)
  | 3. Reads design/design.md, picks a document type and an
  |    accent color from the content's semantic context
  | 4. Writes the content as structured content.json blocks
  |    (headings, body, tables, charts, callouts, math...)
  | 5. Builds: palette -> cover (Playwright/Chromium) ->
  |    body (reportlab) -> merge -> report.pdf
  | 6. Delivers a print-ready PDF
  v
Finished .pdf with a designed cover and typeset body

The key point: steps 2–5 are orchestrated by the LLM following SKILL.md. The user is involved only at the start (describe the request) and the end (acceptance).

The skill routes every task down one of three paths:

Two things the skill enforces on itself that are worth knowing as a user:

• A token-based design system: color, typography and spacing derive from the document type and flow through every page — 15 built-in types (report, proposal, resume, academic, magazine…), each with its own cover pattern and font identity.
• The accent color is chosen from your content, not from a default: legal briefs trend deep navy, healthcare teal-green, creative work burgundy. Name a brand color to override it.

2. Prerequisites

Set these up first — Install skills walks through the install on Windows, macOS and Ubuntu step by step; its Install the skills into an agent section covers installing the skill into each agent (CoDev Code, OpenCode, Claude Code, Codex, Cursor) by hand.

The machine running the agent needs:

• Python 3.10–3.14 with reportlab (body typesetting) and pypdf (fill, merge, reformat) — both required.
• matplotlib (optional — chart, flowchart and math blocks degrade to plain text without it).
• Node.js ≥ 18 + the Playwright module + its Chromium build (cover rendering). The offline install ships Playwright as a prebuilt module tree and unpacks Chromium into Playwright's browser cache; no npm or internet access is needed. On macOS, Playwright's Chromium supports macOS 14+ only — on 13 and older, cover rendering is unavailable.
• Internet at generation time — for cover fonts only (optional): covers load their display fonts live from Google Fonts and nothing is cached locally. Offline, layout and colors are unchanged but cover text falls back to system fonts (Helvetica/Times/Arial) instead of each type's font identity.

The skill ships its own doctor: bash scripts/make.sh check reports every dependency, and the setup script runs it as the pdf verification step. Note the check verifies the Playwright module, not the Chromium binary itself — a missing browser build only surfaces when a cover is actually rendered.

3. How to use it: talk to the agent

The skill self-activates when your prompt contains its signals: PDF, report, proposal, resume, professional document, polished, client-ready, fill the form, reformat… — it is tuned for requests where visual quality matters, not just any PDF output.

Golden rule — provide these 4 groups of information:

1. What: create new / fill a form / reformat an existing doc (the agent can infer, but explicit is better)
2. Which files: input and output files — a plain name plus "in this folder" (report.pdf), or a full path (C:\temp\report.pdf, ~/documents/report.pdf) — and the source doc or form if one exists
3. Content: topic, audience, the actual material — or for forms, the values to fill in
4. Presentation: document type (report, proposal, resume…), brand/accent color, title, author, date

4. Prompt recipes per task type

4.1. Create a styled PDF (CREATE)

Create q3-strategy.pdf in this folder: a client-ready proposal titled
"Q3 Strategy Review" for the leadership team, authored by the Strategy
Team, dated October 2026.
- Sections: market context, three strategic options with a comparison
  table, a quarterly revenue bar chart, recommendation with a callout
- Steel blue accent (#2D5F8A), proposal document type

Tip: naming the document type steers the whole design — a resume gets an oversized typographic cover, a magazine a warm cream hero-image cover, a terminal a monospace neon-on-black identity. See the type table below.

4.2. Fill a PDF form (FILL)

Inspect onboarding.pdf in this folder, list its form fields, then fill it as
onboarding-filled.pdf: FirstName "Jane", LastName "Nguyen", Country dropdown
"US", the "I agree" checkbox ticked. Leave every other field and all styling
untouched.

The agent must run the inspect step first — field names in PDFs are exact and often unintuitive, and dropdown/radio values must match the choices the inspect output reports.

4.3. Reformat an existing document (REFORMAT)

Reformat annual-review.md in this folder into annual-review.pdf: report type,
deep navy accent, title "2026 Annual Review". Keep the content unchanged -
headings, lists and tables map to the design system's blocks.

Supported inputs: .md, .txt, .pdf, .json.

5. Acceptance — make the agent prove it

Ask for evidence before accepting delivery:

"Run the environment check and show me the doc's structure"

A passing delivery includes:

• bash scripts/make.sh check → every dependency ✓ (the same check the installer's verification step runs).
• For fills: a re-run of fill_inspect.py on the output showing the written values, with the untouched fields unchanged.
• For creates/reformats: the content.json block list — a quick way to confirm every section, table and chart made it in before opening the file.

Finally, open the PDF in a viewer: the cover should carry the chosen accent and type identity, tables should carry accent headers, and page flow should be print-ready. The pipeline is deterministic — a tweak ("make the accent darker", "swap sections 2 and 3") just re-runs it.

6. Troubleshooting

7. Skill limitations

• FILL handles AcroForm text, checkbox, dropdown and radio fields — not XFA forms, signature fields, or flattened (non-form) PDFs.
• No password-protected/encrypted files.
• REFORMAT of a .pdf input works from its extracted text — complex source layouts (multi-column, scanned pages) may need a .md/.txt source instead.
• Cover rendering needs Node.js + Playwright + Chromium; without them the skill still produces body-only PDFs. On macOS it additionally requires macOS 14+ (Playwright ships no Chromium build for older versions).
• The cover's font identity (Playfair Display, Syne, Bebas Neue…) requires internet at generation time — fonts come live from Google Fonts and are not cached; offline covers render with system fallback fonts.
• Charts and flowcharts are matplotlib-drawn — styling is the design system's, not hand-tunable per chart.

8. Appendix: document types and scripts

Fifteen document types, each a complete visual identity (cover pattern + typography):

Content blocks available in content.json: headings (h1–h3), body (with <b>/<i> markup), bullet/numbered lists, callout, table, image/figure, code, math (LaTeX via matplotlib), chart (bar/line/pie), flowchart, bibliography, divider, pagebreak, spacer.

The scripts the agent runs under the hood (bash scripts/make.sh <cmd> wraps them):