minimax-pdf

Three tasks. One skill.

Routing Boundary

Use this skill for PDF output, final non-editable deliverables, PDF form filling, print-ready documents, or tasks where visual page fidelity is the deliverable. Use minimax-docx when the user needs editable Word/DOCX output, minimax-xlsx for spreadsheets/formulas/workbooks, and pptx-generator for slides.

Trigger	Use this skill?	Why
"Make a polished client-ready PDF"	Yes	Final PDF/page design
"Fill this PDF form"	Yes	PDF field workflow
"Create an editable Word contract"	No	Route to minimax-docx
"Format an Excel workbook"	No	Route to minimax-xlsx

Read design/design.md before any CREATE or REFORMAT work.

---

Route table

User intent	Route	Scripts used
Generate a new PDF from scratch	CREATE	palette.py → cover.py → render_cover.js → render_body.py → merge.py
Fill / complete form fields in an existing PDF	FILL	fill_inspect.py → fill_write.py
Reformat / re-style an existing document	REFORMAT	reformat_parse.py → then full CREATE pipeline

Rule: when in doubt between CREATE and REFORMAT, ask whether the user has an existing document to start from. If yes → REFORMAT. If no → CREATE.

Route validation gates

1. Classify the route: choose CREATE, FILL, or REFORMAT from the table above before running scripts.
2. Validate inputs: confirm source files exist, output path is writable, and route-specific required values are present.
3. Run the route pipeline: use only the scripts for the selected route; do not mix FILL with CREATE/REFORMAT unless the user explicitly asks for both.
4. Verify route evidence: inspect script output and the resulting PDF before claiming success.

🔴 CHECKPOINT / 🛑 STOP: If the task may alter an existing PDF's visual layout, field positions, page count, signatures, or print-readiness, pause and confirm whether fidelity or content transformation is the priority.

Failure recovery

Trigger condition	First response	If still failing
Route is ambiguous	Ask whether there is an existing source document or fillable PDF	Stop; do not invent a route
make.sh check reports missing tools	Run the documented make.sh fix only with explicit user approval and only if allowed in the environment	Report missing dependency and exact failing tool
CREATE output has overflow, clipped text, or broken charts	Adjust content blocks, page breaks, or chart/table sizing and rebuild	Report affected pages/blocks; do not claim print-ready
FILL field name/value is rejected	Re-run fill_inspect.py and use exact field names/choices	Ask for corrected values; do not guess field mappings
REFORMAT loses structure or images	Prefer a simpler content.json mapping and preserve essential order	Ask whether to prioritize visual match or semantic cleanup

Do not do this

• Do not recreate a fillable PDF from scratch when the user asked to fill fields; preserve the original layout.
• Do not change page size, margins, fonts, form field positions, or signatures during FILL.
• Do not claim visual fidelity from script success alone; inspect the rendered PDF.
• Do not use vivid default colors or decorative effects that conflict with the document's audience.
• Do not overwrite the user's source PDF; always write to a separate output path.

---

Route A: CREATE

Full pipeline — content → design tokens → cover → body → merged PDF.

bash scripts/make.sh run \
  --title "Q3 Strategy Review" --type proposal \
  --author "Strategy Team" --date "October 2025" \
  --accent "#2D5F8A" \
  --content content.json --out report.pdf

Doc types: report · proposal · resume · portfolio · academic · general · minimal · stripe · diagonal · frame · editorial · magazine · darkroom · terminal · poster

Type	Cover pattern	Visual identity
report	fullbleed	Dark bg, dot grid, Playfair Display
proposal	split	Left panel + right geometric, Syne
resume	typographic	Oversized first-word, DM Serif Display
portfolio	atmospheric	Near-black, radial glow, Fraunces
academic	typographic	Light bg, classical serif, EB Garamond
general	fullbleed	Dark slate, Outfit
minimal	minimal	White + single 8px accent bar, Cormorant Garamond
stripe	stripe	3 bold horizontal color bands, Barlow Condensed
diagonal	diagonal	SVG angled cut, dark/light halves, Montserrat
frame	frame	Inset border, corner ornaments, Cormorant
editorial	editorial	Ghost letter, all-caps title, Bebas Neue
magazine	magazine	Warm cream bg, centered stack, hero image, Playfair Display
darkroom	darkroom	Navy bg, centered stack, grayscale image, Playfair Display
terminal	terminal	Near-black, grid lines, monospace, neon green
poster	poster	White bg, thick sidebar, oversized title, Barlow Condensed

Cover extras (inject into tokens via --abstract, --cover-image):

• --abstract "text" — abstract text block on the cover (magazine/darkroom)
• --cover-image "url" — hero image URL/path (magazine, darkroom, poster)

Color overrides — always choose these based on document content:

• --accent "#HEX" — override the accent color; accent_lt is auto-derived by lightening toward white
• --cover-bg "#HEX" — override the cover background color

Accent color selection guidance:

You have creative authority over the accent color. Pick it from the document's semantic context — title, industry, purpose, audience — not from generic "safe" choices. The accent appears on section rules, callout bars, table headers, and the cover: it carries the document's visual identity.

Context	Suggested accent range
Legal / compliance / finance	Deep navy #1C3A5E, charcoal #2E3440, slate #3D4C5E
Healthcare / medical	Teal-green #2A6B5A, cool green #3A7D6A
Technology / engineering	Steel blue #2D5F8A, indigo #3D4F8A
Environmental / sustainability	Forest #2E5E3A, olive #4A5E2A
Creative / arts / culture	Burgundy #6B2A35, plum #5A2A6B, terracotta #8A3A2A
Academic / research	Deep teal #2A5A6B, library blue #2A4A6B
Corporate / neutral	Slate #3D4A5A, graphite #444C56
Luxury / premium	Warm black #1A1208, deep bronze #4A3820

Rule: choose a color that a thoughtful designer would select for this specific document — not the type's default. Muted, desaturated tones work best; avoid vivid primaries. When in doubt, go darker and more neutral.

content.json block types:

Block	Usage	Key fields
h1	Section heading + accent rule	text
h2	Subsection heading	text
h3	Sub-subsection (bold)	text
body	Justified paragraph; supports <b> <i> markup	text
bullet	Unordered list item (• prefix)	text
numbered	Ordered list item — counter auto-resets on non-numbered blocks	text
callout	Highlighted insight box with accent left bar	text
table	Data table — accent header, alternating row tints	headers, rows, col_widths?, caption?
image	Embedded image scaled to column width	path/src, caption?
figure	Image with auto-numbered "Figure N:" caption	path/src, caption?
code	Monospace code block with accent left border	text, language?
math	Display math — LaTeX syntax via matplotlib mathtext	text, label?, caption?
chart	Bar / line / pie chart rendered with matplotlib	chart_type, labels, datasets, title?, x_label?, y_label?, caption?, figure?
flowchart	Process diagram with nodes + edges via matplotlib	nodes, edges, caption?, figure?
bibliography	Numbered reference list with hanging indent	items [{id, text}], title?
divider	Accent-colored full-width rule	—
caption	Small muted label	text
pagebreak	Force a new page	—
spacer	Vertical whitespace	pt (default 12)

chart / flowchart schemas:

{"type":"chart","chart_type":"bar","labels":["Q1","Q2","Q3","Q4"],
 "datasets":[{"label":"Revenue","values":[120,145,132,178]}],"caption":"Q results"}

{"type":"flowchart",
 "nodes":[{"id":"s","label":"Start","shape":"oval"},
          {"id":"p","label":"Process","shape":"rect"},
          {"id":"d","label":"Valid?","shape":"diamond"},
          {"id":"e","label":"End","shape":"oval"}],
 "edges":[{"from":"s","to":"p"},{"from":"p","to":"d"},
          {"from":"d","to":"e","label":"Yes"},{"from":"d","to":"p","label":"No"}]}

{"type":"bibliography","items":[
  {"id":"1","text":"Author (Year). Title. Publisher."}]}

---

Route B: FILL

Fill form fields in an existing PDF without altering layout or design.

# Step 1: inspect
python3 scripts/fill_inspect.py --input form.pdf

# Step 2: fill
python3 scripts/fill_write.py --input form.pdf --out filled.pdf \
  --values '{"FirstName": "Jane", "Agree": "true", "Country": "US"}'

Field type	Value format
text	Any string
checkbox	"true" or "false"
dropdown	Must match a choice value from inspect output
radio	Must match a radio value (often starts with /)

Always run fill_inspect.py first to get exact field names.

---

Route C: REFORMAT

Parse an existing document → content.json → CREATE pipeline.

bash scripts/make.sh reformat \
  --input source.md --title "My Report" --type report --out output.pdf

Supported input formats: .md .txt .pdf .json

---

Environment

bash scripts/make.sh check   # verify all deps
bash scripts/make.sh fix     # auto-install missing deps
bash scripts/make.sh demo    # build a sample PDF

Tool	Used by	Install
Python 3.9+	all .py scripts	system
reportlab	render_body.py	pip install reportlab
pypdf	fill, merge, reformat	pip install pypdf
Node.js 18+	render_cover.js	system
playwright + Chromium	render_cover.js	npm install -g playwright && npx playwright install chromium

Before claiming the PDF complete, fixed, passing, or verified, follow the canonical lifecycle/ordinary-task verification owner and cite the fresh build/form/visual evidence selected for that claim.