presentation-builder

Build a deck the user can speak to. Slides are visual backdrops. The script lives in speaker notes.

Scope

Use for talks, pitches, lectures, and demos where a person presents live.

Do not use for text-heavy handouts or read-ahead decks, formatting one existing slide, spreadsheet charts, or documents. For a handout request, state that this skill keeps on-slide text minimal and ask before continuing.

Inputs

Ask only for what is missing:

• What the user wants to say. Always ask first (Step 1).
• Talk length in minutes. Slide count equals minutes, at about one minute per slide.
• Source material: outline, doc, notes, data, or prior deck.
• Speaking pace if known. Default 5 to 8 bullets, 100 to 160 words per slide.
• Output folder. Default deck/ next to the source material. Do not commit deck files unless asked.

Audience: assume smart newcomers with no background in the topic. Do not talk down to them. Do not ask about familiarity. Change this only if the user explicitly names a more expert audience.

User owns the message, facts, visual picks, and template. Do not invent claims or data for notes.

Rules For Every Slide

• Slide shows a heading of at most 8 words plus visuals. No sentences from the script on the slide.
• Visuals complement what the speaker says at that moment. They never repeat it as text.
• Speaker notes are bullets, one idea each in short spoken sentences, so the speaker can read them word for word if needed. About one minute per slide.
• Every slide tells the audience what they gain.
• Bold key terms in the notes with **term**.
• Short labels on a chart or diagram are fine. Paragraphs are not.

Workflow

Steps 1, 2, 5, and 6 are user gates. Stop and wait at each gate. Do not skip a gate unless the user explicitly delegates that decision.

Step 1: Ask What They Want To Say

Gate: before writing anything, ask the user:

• What are the main points you want to make?
• What is the one thing the audience should remember?
• Which facts, numbers, stories, or examples must be included?

Wait for answers. Use only facts the user gives or source material confirms.

Step 2: Script By Section

Write the script section by section in this flow. Slide count still equals minutes.

1. Opening Hook (1 slide): start with what the audience gains or a problem they already feel. Use a question, a user-supplied fact, or a short story.
2. Core Arguments (most slides): one argument per slide, each framed as a benefit to the audience.
3. Supporting Data/Story (1 to 2 slides): user-supplied numbers, examples, or a story that proves the arguments. Never invent data.
4. Call to Action (last slide): restate the core idea in a bullet starting In short:, then make one specific ask.

Notes per slide: 5 to 8 bullets, 100 to 160 words. Each bullet holds one idea in 1 or 2 short sentences, so the speaker can read it word for word.

Spoken voice:

• Short sentences, max 20 words. Contractions. Talk to the audience as "you".
• Conversational transitions between slides and sections. Examples: "So what does that mean for you?", "Here's the proof.", "Which brings me to my ask."
• Mark natural pauses with [pause]: after the hook, after key numbers, before the ask.
• No essay phrasing: no "furthermore", "in conclusion", or stacked clauses.

Respect the audience:

• Assume no background in the topic and full intelligence. Define a term in a quick clause, then move on.
• Lead each slide with why it matters to the audience, then how it works.
• Avoid "simply", "obviously", "basically", "as you know", and "of course".

Apply CLEAR (same framework as the clear-explanation skill) inside that flow:

• Calibrate: no jargon. Bold each key term with **term** and define it in plain words at first use.
• Link: introduce each new concept with one everyday analogy. State where the analogy stops if it could mislead.
• Envision: give each slide one simple shape the listener can hold: 3-step flow, before/after, cause and effect, or named stages. Step 3 visuals should show this shape.
• Abstract: one idea per bullet. Concrete nouns, active verbs. Cut detail that does not help the audience understand or act. Keep caveats that change decisions. Test: could a newcomer repeat the slide's point after one hearing? If not, simplify.
• Repeat: the Call to Action slide restates the core idea before the ask.

Present the script grouped by section, with heading and bullet notes per slide.

Gate: ask the user to approve or edit the script. Iterate until approved. Accuracy wins over simplicity.

Step 3: Candidate Visuals

For each approved slide write exactly 5 candidate visuals.

• Max 2 sentences each.
• Describe what appears and what it signals. Example: Single upward line on a blank grid, one dot labeled "today". Signals momentum without numbers.
• At least one candidate shows the slide's Envision shape. Another can picture the Link analogy.
• Vary type across the 5: icon composition, diagram, chart, photo or illustration, metaphor.
• Each must support the notes without restating them.

Step 4: Markdown Draft

Write deck/draft.md in this exact shape, one block per slide. Tag each slide with its section in parentheses: Opening Hook, Core Arguments, Supporting Data/Story, or Call to Action.

# Talk Title

## Slide 1 (Opening Hook): Proposed heading

### Visuals
- Candidate visual 1, max 2 sentences.
- Candidate visual 2.
- Candidate visual 3.
- Candidate visual 4.
- Candidate visual 5.

### Speaker notes
- Ever lost a day to a merge? [pause]
- A **merge** combines your work with everyone else's. It shouldn't cost you a day.

Run from repo root:

uv run skills/presentation-builder/scripts/deck.py validate deck/draft.md

Fix every FAIL line and rerun. validate fails on out-of-order or unknown sections. Fix WARN lines (bullet count, notes length, missing bold terms, long sentences, talking-down words, no "you") unless the user approved them.

Step 5: User Picks Visuals

Gate: send deck/draft.md and ask the user to delete every visual bullet they do not want, keeping their picks under each slide. Wait for the edited file.

Then run:

uv run skills/presentation-builder/scripts/deck.py selections deck/draft.md > deck/selections.json

If any slide reports no visual selected, ask the user for that slide. Do not pick for them.

Step 6: Template

Gate: ask for the template file they want used. Require .pptx. For .potx, Keynote, or Google Slides, ask for a .pptx export.

Run:

uv run skills/presentation-builder/scripts/deck.py inspect path/to/template.pptx > deck/template.json

Summarize for the user: theme fonts, allowed sizes, color palette, layouts, and icon inventory.

Strict template rules:

• Template icons are the core visual source. Build each selected visual from them first.
• Use only template colors. Prefer theme color references.
• Use only template fonts and font sizes. Let placeholders inherit where possible.
• Use template layouts and their placeholder grid.
• Native shapes and charts are allowed when styled only with template colors, fonts, and sizes.
• If a selected visual cannot be built this way, ask the user: swap the visual, simplify it, or approve an outside asset by name.

Step 7: Render Final Deck

Load render-guide.md now. Build deck/final.pptx from the template file, one slide per entry in selections.json, carrying approved notes unchanged.

Verification

Run:

uv run skills/presentation-builder/scripts/deck.py check deck/final.pptx path/to/template.pptx --selections deck/selections.json

It must print PASS. It fails on non-template fonts, sizes, colors, or images, empty notes, and slide-count mismatch. Each approved outside asset will fail the image check; list those as approved exceptions.

Then render slide images and inspect each one for overflow, overlap, unreadable icons, low contrast, leftover template text, and empty placeholders. Confirm every slide's notes match the approved script.

Fallbacks

• Notes only requested: run Steps 1 and 2, then stop.
• User declines a template: offer a plain deck with a white background, black text, the heading, the chosen visuals, and notes. Do not invent a style.
• User delegates visual picks: choose one per slide, give a one-line reason each, and write selections.json in the same shape.
• No uv: pip install python-pptx then python skills/presentation-builder/scripts/deck.py ....
• No slide renderer: run check, then ask the user to open the deck and confirm layout.

Output

At each gate return file paths and one direct question. At the end return deck/final.pptx, check result, slides reviewed visually, approved exceptions, and open issues.

Writing

Use direct simple sentences. Skip rhetorical flourishes. Avoid X-not-Y contrasts, self-answering rhetorical questions, em dashes, alliterative three-part phrases, vague inspirational pivots, unsourced claims, and unverified quotes.