Pptfast

pptfast — deck generation playbook

pptfast turns a JSON IR (intermediate representation) into a native DrawingML .pptx — every shape stays editable in PowerPoint. You own the content model. The tool owns layout, style, and motion. You never draw SVG or position anything: pick from a controlled vocabulary and let the validate gate catch what will not fit.

Run it

Everything in this playbook runs through the CLI: schema, spec/assemble, validate, render, audit, preview, serve, brand extract. Every one of those commands goes through the launcher bundled with this skill, which resolves a working runtime for you. Replace `` with the directory this SKILL.md lives in:

bash /scripts/run.sh                                        # macOS / Linux
powershell -ExecutionPolicy Bypass -File \scripts\run.ps1   # Windows

It tries a compatible pptfast on PATH first, then npx, then bunx, forwarding your arguments and its exit code unchanged. Nothing to install first, and the version it runs is pinned to this skill. Exit 78 means no runtime at all: relay the nextSteps from its stderr JSON instead of retrying.

Wherever this playbook writes pptfast , run it through that launcher.

Right after an install, and any time a command misbehaves in a way the error message does not explain, run pptfast doctor before anything else. It reports the runtime, every installed skill copy and whether one is stale, the dsh plugin's version, which optional capabilities are present, and a self-test render. Relay what it says instead of guessing.

If your harness forbids running scripts, work down the same order by hand and use the first line that applies:

1. A pptfast on PATH at the same major version as the pin below and no older: pptfast .
2. Otherwise, if npx exists: npx --yes --package @liustack/pptfast@0.20.0 pptfast .
3. Otherwise, if bunx exists: bunx --bun @liustack/pptfast@0.20.0 .
4. Otherwise tell the user no JavaScript runtime was found, and that installing Node 22.19+ (https://nodejs.org) or Bun (https://bun.sh) is the next step. Do not report pptfast itself as broken.

Workflow

Six phases: read the vocabulary, spec and confirm, fill pages in batches, render, self-check, revise. For a very small deck (a handful of slides), skip the spec and write a single IR file directly, validating with pptfast validate — everything below still applies with "the deck project directory" read as "the IR file", minus phase 2's spec step.

Phase 1 — Read the vocabulary (do this fresh every session)

pptfast schema             # IR JSON Schema: the single source of truth
pptfast schema --spec      # deck spec schema
pptfast narratives --json  # named narrative presets (strategy/pacing/audience axes + theme recommendations)
pptfast themes --json      # built-in themes (id + label)

Never write IR or a spec from memory of a previous session or from this file — the schema evolves and schema/narratives/themes output always wins.

Boundary-page rule — learn this now, it is the single most common mistake: cover, chapter, and ending pages never render components or footnote, on any archetype, no exceptions. Put that content on a content page instead. Getting this wrong at spec time means rewriting real content later — validate catches it with "" slides do not render components/footnote — move this content to a content slide or remove it, but by then you have already drafted content that has to move.

// pages/closing.json — spec type "ending" — WRONG: components never render on an ending page
{ "components": [{ "type": "bullets", "items": ["Thank you", "Questions? sales@example.com"] }] }

// pages/wrap-up.json — spec type "content", inserted right before the ending page — CORRECT
{ "components": [{ "type": "bullets", "items": ["Thank you", "Questions? sales@example.com"] }] }

// pages/closing.json — spec type "ending" — stays bare, nothing to move here
{}

docs/deck-projects.md's boundary-page render surface table has the full per-type accounting.

Phase 2 — Spec and confirm

Propose and confirm before writing any page content:

• Narrative first: pick a named preset (or override individual axes) from narratives output that matches the deck's purpose and audience — this is a decision layer above theme, not a visual choice
• Theme id next, from the chosen narrative's themeRecommendations (or pick from themes output to match the deck's tone if none fit — a recommendation, never a constraint). If the user supplied a company template, extract it into a custom theme first — see Brand themes below
• Draft deck.spec.json: one entry per page (id, type, heading, optionally beat/focus/summary) — opens on cover, closes on ending, everything in between is content or chapter
• Run pptfast spec validate deck.spec.json and fix whatever it reports until it prints OK — the hard gates (boundary pages, heading length, beat rotation, page count vs. pacing) all fire here, before a single page is written
• Once spec validate prints OK, set a seed (any integer) in deck.spec.json for revision stability — write one now, or run pptfast assemble once in phase 3 and copy the generated seed … value it prints into the spec. Without a persisted seed, editing one page's heading later can reshuffle every other page's auto-picked layout

After the user confirms the validated spec, do not re-spec. Restructuring a confirmed spec (reordering, retyping, dropping pages) silently wastes the user's review. If new information genuinely forces a change, say so and re-confirm first, then re-run spec validate.

Phase 3 — Fill pages in batches of at most 4, validate immediately

For each page in the confirmed spec, write pages/.json with its content (components, and optionally layout/arrangement/background/image_side/footnote/notes — never type/heading, those are locked by the spec). Remember Phase 1's boundary-page rule while drafting cover/chapter/ending pages — do not give them components or footnote and then have to move it. notes is speaker notes prose for whoever presents the deck — writing a good speaking script is a model strength, so draft it whenever the page's content calls for a spoken walkthrough beyond what's on the slide.

pptfast assemble deck-dir/     # materializes deck.json — catches structural drift: orphan page files, locked-field violations, a broken spec
pptfast validate deck-dir/     # content-quality gate: heading length, density, bullets budget (warnings) + unknown theme, boundary-page content, and a bullet item past render-safety (hard errors)

Fix whatever either command reports as an error and re-run until both print OK. validate can print OK alongside warning: lines (e.g. a long heading or a dense slide) — tighten those too when practical, they read better, but they do not block. Only an error stops OK from printing. A spec page with no page file yet is a placeholder (heading only) — assemble and validate both accept that. Leaving some pages as placeholders between batches is normal, not an error. assemble also prints note: N layouts auto-selected into deck.json whenever a page's layout was left to auto-selection — informational, not an error. Pin layout in a page file only when a specific pick needs to be locked — a pinOnly layout like quote-stage needs this pin every single time, since it never comes up through auto-selection at all (see Quote-stage below).

Phase 4 — Render

pptfast render deck-dir/ -o deck.pptx

--theme overrides the deck theme without editing the spec. --style layers a style-token override on top (re-color without forking a theme, schema: pptfast schema --style). Render refuses a deck with unfilled placeholder pages unless you add --draft — reach for that only when the user explicitly wants a look before every page is done. It also refuses a deck where a page holds more than fits, so the layout left blocks out with nothing on the slide to say so: the error names the pages and how many blocks each lost. Fix it by shortening that page or splitting it in two, and re-render — --allow-dropped-content ships the file with the content missing, so only pass it if the user says to.

If the project has a pptfast.config.json, its theme/style are project defaults — do not fight them with --theme unless the user asks. Any page notes you wrote in phase 3 export as native PowerPoint speaker notes (View → Notes in PowerPoint/Keynote) — never drawn onto the slide itself.

Phase 5 — Audit and optional visual self-check

Once every page is filled (no placeholders left), run the deterministic geometry audit:

pptfast audit deck-dir/

Zero-token, zero-variance — it renders each page off-screen and checks overflow, out-of-bounds, low-contrast, overlap, content-truncated (an ellipsis cut real text), and content-dropped (a "+N more" marker hiding an item or a whole component), exiting 1 when it finds anything (0 when clean). Each finding names its page (and id) and carries a fix. Fix the flagged page's content — same "restructure, don't delete" discipline as a validate error — then re-run pptfast audit deck-dir/ alone (no need to re-render) until it exits 0. This is the deck's visual QA. Do not rely on eyeballing a screenshot instead.

If any page has a cover/chapter photo background, add --pixels — it rasterizes the page and samples real pixels to catch text sitting directly on an unscrimmed photo, the one case the SVG-only checks above can't see.

pptfast preview deck-dir/ -o preview/ --html

Writes one standalone SVG per slide plus a self-contained preview.html, never gated on placeholder pages. Read a few SVGs yourself (they are plain text files) to sanity-check layout and density before delivering, especially for image-heavy decks — hand preview.html (thumbnail strip, keyboard navigation, placeholder badges) to the user for their own look instead. When every page is filled, preview.html also overlays the same audit findings (per-page badges + a findings panel) so the reviewer sees them without a terminal — a deck with any placeholder page shows a one-line "audit skipped" notice instead. preview.html is read-only: it shows the deck, it never edits it. When the reviewer wants something changed, they tell you in the conversation — a screenshot of the page in question is the fastest way for both of you — and you route it through phase 6.

Showing the deck to the user

How you hand a deck over depends on what the harness can render, and the two options are not equivalent — take the first one that is available.

If a pptfast_preview tool exists, call it. It renders the deck and puts a real slide preview in the conversation: a thumbnail strip in the tool card, full size on click, arrow keys to page. The user sees the deck without leaving the thread and without opening anything. Never fall back to handing over a URL when this tool is present — that is the experience it was built to replace. The tool reports only a summary line back to you (page count, audit state); that is deliberate, the deck itself goes to the user's screen, not into your context.

Otherwise, serve it. Most harnesses have no way to draw a slide in the transcript, so the review happens in the user's own browser. Never try to substitute by pasting a thumbnail or a screenshot of one page into the conversation. Serve the whole thing and let the user page through it at full size. Start the server as a background task (in DSH, follow the background-job convention and note the job id so you can stop it later):

pptfast serve deck-dir/ --no-open

Then run the round in this order:

1. Always pass --no-open. There is no browser to auto-open in an agent environment.
2. Report the exact localhost URL it prints (default http://127.0.0.1:4400) to the user, so they can open it themselves. That one line is the whole handoff.
3. The user pages through the deck and tells you what needs changing, in the conversation. A screenshot of the offending page is the fastest hand-off — you see exactly what they see.
4. Route each request through phase 6's revision flow. The page live-reloads on every file you save, so each revision lands in the tab the user already has open. No new link, no re-export, nothing for them to click.
5. Stay in the loop while they keep looking. When the round is over, stop the serve process (kill the background job). Never leave it running after the task ends.

Phase 6 — Revision: edit one page, re-assemble

A revision touches the smallest file that captures it:

• Content change ("punch up the KPI page") → edit that page's pages/.json only, then repeat phase 3's assemble + validate pair, and phase 5's audit, before re-rendering. Never regenerate pages nobody asked you to touch.
• Structural change (reorder, add/remove a page, change a page's type or heading) → edit deck.spec.json instead, re-run pptfast spec validate first (phase 2's no-respeccing rule still applies: only do this when the user actually asked for a structural change).
• A change the reviewer asked for in conversation (usually with a screenshot of the page) → find that page's pages/.json by matching what they described against deck.spec.json/pages/, and treat their words as a requirement to interpret, not a patch to apply verbatim: they are describing a rendered slide, not writing page-file JSON. Translate it into a concrete content edit, then run the same content-change loop above (assemble + validate + audit) for every page you touched. Preview stays read-only end to end: nothing writes into pages/*.json except your own deliberate edit.

Routing a follow-up request

Once a deck project exists, a follow-up message routes into exactly one of three branches — decide which before doing anything:

1. Edit a page ("change slide 3", "make the KPI page punchier", or a screenshot with a note) → phase 6: edit that page's file, re-assemble, re-validate, re-audit. Never touch pages nobody asked about.
2. A new deck (a different topic, audience, or an explicit request to start over) → phase 1: a new deck project directory, fresh narrative/theme decision, fresh spec.
3. Unrelated to deck generation (a question about the content, anything with no connection to slides) → do not invoke pptfast at all.

Brand themes — the user's own company template

When the user hands over (or mentions having) a company template — a .thmx theme, .potx template, or any branded .pptx — extract its colors and fonts into a custom theme before picking a built-in theme in phase 2. Extraction runs entirely locally; the file never leaves the machine.

pptfast brand extract corp-template.pptx -o deck-dir/theme.json --id acme
pptfast render deck-dir/ -o deck.pptx     # theme.json auto-loads; set "theme": "acme" in deck.spec.json

A theme.json sitting in the deck project directory auto-loads on every command (validate/render/audit/preview/serve) — reference its id from deck.spec.json and no flag is needed. For a single IR file, pass --theme-file deck-dir/theme.json instead (works on the same five commands). Loading enforces a contrast floor: a template whose text/background tones are too close is refused with the failing token and ratio named — relay that message and ask the user whether to adjust the extracted file's colors or fall back to a built-in theme.

Content methodology

Component selection

| Content shape | Use | Not | |---|---|---| | 2–5 headline metrics | kpi_cards | chart | | Series data (trend, comparison, share) | chart (bar/line/pie/funnel/dumbbell/scatter/area/donut/gauge) | numbers buried in bullets | | Exact figures the audience reads row-by-row (price list, spec sheet, metrics-by-pe

…

Source & license

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

• Author: liustack
• Source: liustack/pptfast
• License: MIT

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