| name | new-typst-template |
| description | Scaffold a parameterised Typst template for batch document rendering. Use when the user asks to create a Typst template, build an invoice/receipt/statement/report/letter template, or set up a JSON-data-driven Typst document for batch CLI rendering. Produces a `.typ` template that consumes a JSON sidecar so N documents can be rendered from N data files. |
new-typst-template
Scaffold a reusable Typst template parameterised over a JSON data file. The template is designed for batch rendering via the Typst CLI: one .typ template + N JSON files = N PDFs.
When to use
Auto-trigger when the user asks for a programmatic Typst template, especially for:
- Invoices, receipts, statements
- Reports with repeating sections (line items, transactions, attendees)
- Branded letters, certificates
- Anything where the same layout is rendered repeatedly with different data
If the user just wants a one-off styled document (not parameterised, not batch), the standalone typst skill is a better fit — point them to it instead.
Inputs to gather
- Template type — invoice, receipt, statement, report, letter, certificate, custom.
- Required fields — what variable data does the template consume? Get a list or a sample JSON. If the user has a sample document instead of a field list, route them to
ingest-document-sample first.
- Brand profile — check for
$CLAUDE_USER_DATA_ROOT/brand.json (see path resolution below). If present, use it. If not, ask whether to run define-brand-profile first or proceed with placeholder branding.
- Output directory — where the template files should live. Default: ask the user; suggest
~/Documents/doc-templates/<template-name>/.
Path resolution
Resolve the plugin data root once per session:
DATA_ROOT="${CLAUDE_USER_DATA:-${XDG_DATA_HOME:-$HOME/.local/share}/claude-plugins}/programmatic-doc-generation"
mkdir -p "$DATA_ROOT"
Read $DATA_ROOT/config.json for any pointers (e.g. user-chosen templates path).
Read $DATA_ROOT/brand.json for brand profile, if present.
Template scaffold
For an invoice (other types follow the same pattern), produce:
<template-dir>/
├── template.typ # the Typst template
├── data.example.json # example payload — schema reference
├── render.sh # batch render helper
└── README.md # how to use, what each field does
template.typ should:
- Accept its data via
#let data = json("data.json") at the top.
- Use brand colours/logo from the brand profile if available.
- Include a clearly commented "fields consumed" header listing every JSON path the template reads.
- Use Typst's
#for over arrays (line items, sections) rather than hardcoded slots.
render.sh should iterate over a data/*.json directory and emit out/<basename>.pdf for each — one CLI call per file via typst compile.
After scaffolding
- Run
typst compile once against the example data to verify it builds. If typst isn't installed, instruct the user how to install it (don't try to install it for them on a system you don't fully own).
- Tell the user how to add new data files and re-run
render.sh, and point at batch-render-typst for the batch flow.
Storage rules
- Template files belong wherever the user chooses (their work, their data) — typically under
~/Documents/ or ~/repos/. Store only the path pointer in $DATA_ROOT/config.json.
- Never write template content into the plugin install directory.
