Presentation Generator

Presentation Generator

Image-as-slide decks. Every slide is a single 16:9 PNG generated by gpt-image-2. The slide is free to be anything visual: a cinematic photograph, a structured infographic with stacked principle cards, an architecture flowchart, a big-number stat, a comparison split-screen, a UI mockup with side annotations, a quote card, a do/don't table, an icon grid, a timeline, a hand-drawn whiteboard sketch.

The skill's job is to make Claude think like a creative director — narrative arc first, visual style locked, composition chosen per slide, prompts engineered with intention — before spending API tokens on imagery.

The two axes of a slide

• Style (locks at the deck level): aesthetic, palette, typography vibe, decorative motif. Constant across all slides — this is what makes the deck feel like one artifact.
• Composition (varies per slide): is this slide a hero photo, a flowchart, an infographic, a big number, a comparison? Pick what serves the slide's job.

Both NotebookLM's Cinematic Video Overviews and well-designed brand decks do exactly this. Lock style; vary composition.

The six phases

Research → Narrative Plan → Style Lock → Parallel Generation (×4) → QA → Assemble

Runs end-to-end autonomously. No approval gate between phases.

Phase 1 — Research

Build a dossier on the topic before touching the deck.

• Local files referenced ("the project plan", a path, a slug) → read with the Read tool.
• Online topic → WebSearch + WebFetch.
• Mixed → both. Local files are ground truth; online is supporting context.
• Brand book exists → if there's a BRAND.md from the brand-system skill in the project, read it. Use its palette, typography, and motif language verbatim in the deck-plan's style_brief. Set brand_source in the plan to point at it. This gives pixel-tight brand fidelity.

Keep the dossier in working memory: 5-15 key facts, quotes worth surfacing, numbers worth visualizing, audience signals.

Phase 2 — Narrative Plan

This is the most important step in the entire workflow. It is what separates a memorable deck from a generic one. Read reference/narrative-frameworks.md first.

Before drafting, answer in your head (or out loud):

1. Audience — who is this for, and what's their starting state of mind?
2. One takeaway — the one thing they must walk away believing.
3. SCQA — Situation → Complication → Question → Answer.
4. Slide count — default 8-10 (Kawasaki). 6 for a quick brief, 12 for a deep explainer. Hard cap at 15 unless the user explicitly asks for more.
5. Tone — formal / conversational / inspiring / pragmatic. Pick one.
6. Visual aesthetic — modern editorial photography / dark UI infographic / hand-drawn whiteboard / cinematic moody / minimalist tech / corporate isometric. Pick one. Lock it.
7. Palette — 3-5 hex colors. Primary, accent, neutrals.
8. Recurring motif — a visual element that appears (in some form) on most slides to tie them together. See reference/visual-style-brief.md.

Then write deck-plan.json to the cwd. Use the schema in templates/deck-plan.schema.json and the worked example in templates/deck-plan.example.json — the example is an 8-slide infographic deck with eight different compositions.

Every slide entry has:

• id — 01, 02, ..., zero-padded
• role — free-form: this slide's narrative function ("cover", "establish problem with visceral contrast", "land the headline metric", "walk through the architecture", "closing CTA"). Descriptive, not from an enum.
• composition — free-form: this slide's visual format. Examples: "title cover with central decorative motif", "comparison split-screen (left = current, right = proposed)", "stacked principle cards (4 cards with icon + heading + body)", "big-number callout with supporting metric cards", "architecture flowchart with router and three branches", "horizontal timeline with three milestone cards", "two-column do/don't comparison table", "three-column checklist". Pick the composition that fits the slide's job. Read reference/slide-compositions.md for the full vocabulary — 15+ formats with prompt skeletons.
• idea — one sentence: the single thing this slide must communicate.
• text_in_image — exact text to render IN the image. Headlines, labels, the quote, the big number, axis labels, callout text. Use exact wording. For Hebrew / Arabic / CJK, write in the target script. Empty string for image-only slides.
• image_prompt — the engineered prompt sent to openai-image.sh. Describe the composition explicitly (where elements sit on the canvas), the subject of each element, and any text-in-image with exact wording in quotes. Don't repeat the deck's style_brief — it's appended automatically. See reference/image-prompting.md.
• speaker_notes — 40-60 words of narration the presenter says while this slide is up.
• model — usually openai. Use gemini only if the slide needs >2 reference images merged or has been failing on openai.

The deck plan also has top-level fields: title, subtitle, audience, takeaway, aesthetic, palette (array of hex), motif, style_brief (a paragraph that gets injected into every image prompt), and optional brand_source and language.

Phase 3 — Style Lock

~/.claude/skills/presentation-generator/scripts/lock-style.py \
  --plan deck-plan.json \
  --output-dir ./refs/

Generates 1-2 abstract reference frames from the style_brief alone — no slide content yet, just the aesthetic, palette, and motif.

Read the resulting PNGs with the Read tool. Claude is multimodal — actually look at the pixels. Score them:

• Is the palette right (compare hex codes to the planned palette)?
• Does the motif read as intended?
• Does the aesthetic match what you wrote?

If both refs land, pick the stronger one and set its path as style_ref in deck-plan.json. If neither lands, edit the style_brief and re-run. If the refs are mediocre but acceptable, ship them — Phase 5 QA will catch drift.

The chosen ref gets passed to openai-image.sh via --ref for every subsequent slide. This is what makes 8-10 independently-generated slides — even with totally different compositions — feel like one coherent deck.

Sibling decks — reuse the style ref. When the user is building a related deck for the same engagement (e.g., a product plan + a quote, or a pitch deck + an internal explainer), set both deck-plans' style_ref field to the same ref PNG path — copy or symlink it into the second deck's refs/ folder, or point both at an absolute path. Skip Phase 3 entirely for the second deck. This guarantees the two decks read as one engagement (same palette tone, same accent treatment, same motif), which is exactly what brand consistency demands.

Phase 4 — Parallel Generation (concurrency 4)

~/.claude/skills/presentation-generator/scripts/generate-deck.py \
  --plan deck-plan.json \
  --output-dir ./slides/ \
  --concurrency 4

Reads the deck plan, builds one shell command per slide (calling openai-image.sh by default), and runs them through a Python ThreadPoolExecutor(max_workers=4). The deck's style_brief is appended to every per-slide prompt. The style_ref is passed via --ref for style coherence.

Outputs land in ./slides/slide-NN-<slug>.png. Default size: 2560×1440 (16:9, both edges multiples of 16 — required by gpt-image-2; 1920×1080 is invalid because 1080 isn't a multiple of 16). Quality: high. Background: opaque.

Progress streams to stderr. On failure, the slide is logged but does not kill siblings.

Phase 5 — QA

~/.claude/skills/presentation-generator/scripts/qa-slides.py \
  --plan deck-plan.json \
  --slides-dir ./slides/

Mechanical checks (file exists, dimensions correct, file size sane, not all-black/white). Then visual QA: Claude reads every slide PNG with the Read tool and scores it against the slide's idea, composition, and text_in_image:

• Did the composition land (right format, right layout)?
• Is text legible and spelled correctly? (Pay close attention to in-image text — the model's biggest failure mode is mangled letterforms or wrong wording.)
• Does the palette adhere to the plan?
• Is the motif present?
• Any defects (broken geometry, drifted style, wrong icons)?

Slides that fail visual QA get regenerated with a refined prompt. Cap at 2 retries per slide. If a slide still fails after 2 retries, surface it to the user with a specific description of what's wrong.

Phase 6 — Assemble

Always emits both PDF and PPTX by default. Pass --format pdf or --format pptx to constrain.

# PDF (HTML deck → Chrome headless)
~/.claude/skills/presentation-generator/scripts/render-pdf.sh \
  --plan deck-plan.json \
  --slides-dir ./slides/ \
  --output ./output/<deck-slug>-v1.pdf

# PPTX (python-pptx, 13.333" × 7.5", full-bleed image, speaker notes attached)
~/.claude/skills/presentation-generator/scripts/build-pptx.py \
  --plan deck-plan.json \
  --slides-dir ./slides/ \
  --output ./output/<deck-slug>-v1.pptx

Both run sequentially after Phase 5 (cheap relative to image generation). See reference/output-formats.md for dimension specifics.

Output convention

./
├── deck-plan.json          # The narrative + composition plan
├── refs/
│   ├── style-ref-1.png
│   └── style-ref-2.png
├── slides/
│   ├── slide-01-cover.png
│   ├── slide-02-comparison-split.png
│   └── ...
└── output/
    ├── <deck-slug>-v1.pdf
    └── <deck-slug>-v1.pptx

What's the style, what's the composition?

Before writing the deck plan, hold this distinction in your head:

If you find yourself describing the palette per slide, you're doing it wrong — push it up to style_brief. If you find yourself describing layouts in style_brief, push them down to per-slide composition/image_prompt.

Composition rhythm — alternate to keep audiences awake

No two adjacent slides should use the same composition. Alternate high-info structured slides (cards, diagrams, charts) with low-info atmospheric slides (photo, quote, big-number). NotebookLM does this rigorously. So does any well-designed deck.

A typical 8-slide rhythm:

1. cover with motif      ← title card
2. comparison split      ← problem statement, visceral contrast
3. stacked principle cards ← codify the philosophy
4. big-number callout    ← land the headline metric
5. architecture flowchart ← show how it works
6. timeline with cards   ← roadmap
7. do/don't comparison   ← brand voice / anti-patterns
8. three-column checklist ← CTA / next steps

Eight slides, eight different compositions, one consistent palette and motif. Reference: see templates/deck-plan.example.json for this exact structure as a worked example.

Hebrew / RTL / non-Latin scripts

gpt-image-2 renders Hebrew, Arabic, CJK, Hindi, and Bengali materially better than any prior model. For decks in those languages: write text_in_image in the target script, set language accordingly in the deck plan, and proceed normally. For long Hebrew/RTL paragraphs that come out garbled, see ~/.claude/skills/image-generation/reference/hebrew-rtl.md for the fallback two-stage workflow.

When NOT to use this skill

• The user wants a text document, Google Doc, or Notion page.
• The user wants natively-editable PowerPoint with rewritable text-and-shape slides → use the official anthropics/skills pptx skill.
• The user wants a single hero image or marketing visual → use the image-generation skill directly.
• The user wants a video / animated explainer → out of scope. Static decks only.

API keys and dependencies

• OPENAI_IMAGE_API_KEY — required. From ~/.claude/projects/-Users-shaharshavit/memory/api-keys.md → "OpenAI (image generation)".
• GEMINI_IMAGE_API_KEY — optional. Only needed if any slide opts into model: gemini.
• Python 3.10+ with python-pptx (pip install python-pptx) and Pillow.
• Chrome / Chromium — for PDF rendering.

Cost discipline

A 10-slide deck at gpt-image-2 high (2560×1440) costs roughly $3-5 per generation pass, plus 2 style-lock refs ($0.40) and any QA-driven regenerations. Budget **$6 per finished deck**. If you exceed $12 on a single deck, stop and consult the user.

Reference docs