Utility Slideshow Creator

<!-- PM-Skills | https://github.com/product-on-purpose/pm-skills | Apache 2.0 -->

Slideshow Creator

Generate professional presentations (.pptx and .pdf) from a JSON deck specification. Zero design decisions at generation time - Claude selects slide types and fills content slots; all visual properties are pre-decided by the theme.

When to Use

• Creating slide decks for stakeholder updates, product reviews, team presentations
• Generating professional .pptx files from content briefs
• Producing consistent presentations without manual formatting
• Exporting presentations to PDF for sharing or archiving

When NOT to Use

• Creating complex data visualizations (use dedicated charting tools)
• Building interactive web presentations (this produces .pptx, not HTML)
• Editing existing PowerPoint files (this creates new decks from scratch)

How It Works

Two-phase architecture:

1. Spec phase (Claude) - Read the content brief, select slide types using decision logic, write a JSON deck specification. Content slots have character limits calibrated to prevent overflow. This is the only phase that costs tokens. 2. Generation phase (Local script) - Run node scripts/generate-deck.js deck-spec.json to produce .pptx. Optionally run node scripts/export-pdf.mjs deck-spec.json for PDF. Deterministic rendering, zero token cost.

Both outputs come from the same JSON spec, so .pptx and .pdf always match.

18 Slide Types

Full slot definitions and character limits: references/slide-types.md

Decision Logic (Quick Reference)

Full decision logic with variant strategy: references/decision-logic.md

JSON Deck Spec Format

{
  "title": "Q3 Product Update",
  "author": "Product Team",
  "footerText": "Internal . Q3 Review",
  "slides": [
    { "type": "title_dark", "title": "Q3 Product Update", "subtitle": "October 2026" },
    { "type": "stat", "stat": "94%", "label": "Customer satisfaction score", "accentColor": "secondary" },
    { "type": "bullets", "title": "What Shipped", "bullets": ["Feature A", "Feature B", "Feature C"] },
    { "type": "closing" }
  ]
}

Colors accept theme token names ("accent", "secondary", "tertiary", "warm") or 6-character hex strings ("2563EB").

Full schema and workflow: references/TEMPLATE.md and references/platform-rules.md

Instructions

1. Read the content brief - Understand topic, audience, length, specific requirements 2. Plan the deck - Select slide types using the decision logic table. Assign dark/light variants for visual rhythm (alternate to avoid monotony). 3. Write the JSON deck specification - Fill content slots, respecting character limits from references/slide-types.md 4. Run the generation script - node scripts/generate-deck.js deck-spec.json 5. Optionally export PDF - node scripts/export-pdf.mjs deck-spec.json output.pdf 6. Report the output - Tell the user where the file(s) are

Output Contract

• Planning artifact: JSON deck specification (the file Claude writes)
• Final output: .pptx file (+ optional .pdf), generated locally from the spec
• Quality gate: All items in the quality checklist pass

Quality Checklist

• [ ] Every slide has a valid type key (one of the 18 defined types)
• [ ] All content slots respect character limits from references/slide-types.md
• [ ] Dark/light variants alternate for visual rhythm (no 3+ consecutive same-variant slides)
• [ ] Deck has a title slide (first) and a closing slide (last)
• [ ] Section dividers separate distinct topics in decks > 6 slides
• [ ] Speaker notes included for key slides (stats, highlights, transitions)
• [ ] JSON is valid (no trailing commas, proper quoting, correct nesting)
• [ ] Color values are valid theme tokens or 6-character hex strings (no # prefix)

References

utility-slideshow-creator - Version History

1.0.1 (2026-06-10)

Description-only patch (F-12 Batch 0, from the 2026-06-09 repo audit): removed the promise of custom themes via utility-slideshow-themer, a skill that has never existed; the references document theme tokens on the default theme only. No body, template, or behavior changes.

1.0.0 (2026-04-08)

Baseline row for the prior published version; see git history for its changes.

Decision Logic

How to select slide types for content and when to use dark vs. light variants.

Content Pattern to Slide Type

When Two Types Could Work

• Single metric with context: Use stat if the number is the star. Use highlight if the insight matters more than the number.
• List of items: Use bullets for 3-6 plain points. Use icon_rows when each item deserves its own visual identity (max 4). Use three_card when items have sub-bullets (exactly 3).
• Sequential information: Use timeline for dates and milestones (chronological). Use process_flow for workflows (action-oriented).
• Two things compared: Use two_col for lists. Use dual_stat for numbers.

Dark/Light Variant Strategy

Alternate variants for visual rhythm. A monotone deck causes slide fatigue.

General rules:

• Section dividers and quotes default dark
• Content, data, tables, and highlights default light
• Alternate within a section to prevent visual monotony
• Title and closing are always dark (or title_light for internal decks)

Suggested rhythm pattern:

TITLE (dark) > SECTION (dark) > CONTENT (light) > STAT (light) >
BULLETS (dark) > HIGHLIGHT (light) > CLOSING (dark)

Override the defaults when:

• Two consecutive slides would have the same variant - flip one
• A stat or highlight needs extra emphasis - use the non-default variant
• The deck is short (< 6 slides) - defaults are usually fine as-is

Deck Length Guidelines

Always include a title slide and a closing slide. Use section dividers when the deck has distinct topics.

Example: Q3 Product Update Deck

This example walks through creating a 9-slide product update deck for an engineering all-hands meeting, demonstrating the spec-writing workflow from content brief to JSON output.

Content Brief

The product team needs a deck for the Q3 engineering all-hands covering:

• Customer satisfaction hit a record high (94%)
• Three major features shipped (real-time analytics dashboard, API rate limiting, bulk data import)
• Revenue grew 18% quarter-over-quarter
• Roadmap preview for Q4 (3 milestones)
• Key insight: teams using the analytics dashboard have 2.4x faster incident response times

Deck Planning

Slide Type Selection

Variant Check

Dark-light alternation: D, D, L, D, L, D, L, L, D -- slight imbalance at slides 7-8 (both light) but acceptable because highlight and timeline are visually distinct types.

JSON Deck Specification

{
  "title": "Q3 Product Update",
  "author": "Product Team",
  "footerText": "Internal -- Engineering All-Hands",
  "outputFileName": "q3-product-update.pptx",
  "slides": [
    {
      "type": "title_dark",
      "title": "Q3 Product\nUpdate",
      "subtitle": "Engineering All-Hands -- October 2026",
      "notes": "Welcome everyone. Quick overview of what shipped and what's ahead."
    },
    {
      "type": "section",
      "title": "Key\nMetrics",
      "variant": "dark",
      "notes": "Starting with our headline performance numbers."
    },
    {
      "type": "stat",
      "stat": "94%",
      "label": "Customer satisfaction -- highest score this year",
      "accentColor": "secondary",
      "variant": "light",
      "notes": "Up from 88% in Q2. Primary driver: faster support response times from the new dashboard."
    },
    {
      "type": "dual_stat",
      "title": "Revenue Growth",
      "leftStat": "$3.2M",
      "leftLabel": "Q2 recurring revenue",
      "leftColor": "muted",
      "rightStat": "$3.8M",
      "rightLabel": "Q3 recurring revenue",
      "rightColor": "accent",
      "variant": "dark",
      "notes": "18% QoQ growth. Bulk import feature drove 40% of new contract value."
    },
    {
      "type": "bullets",
      "title": "What Shipped in Q3",
      "bullets": [
        "Real-time analytics dashboard with customizable widgets",
        "API rate limiting with per-client quotas and alerting",
        "Bulk data import supporting CSV, JSON, and XML formats",
        "SSO integration for enterprise customers"
      ],
      "variant": "light",
      "notes": "Four major features. Each had full rollout with zero critical incidents."
    },
    {
      "type": "three_card",
      "title": "Feature Highlights",
      "cards": [
        {
          "title": "Analytics Dashboard",
          "bullets": ["Real-time metrics", "Custom widgets", "Export to PDF"],
          "color": "accent"
        },
        {
          "title": "API Rate Limiting",
          "bullets": ["Per-client quotas", "Automatic alerting", "Usage dashboard"],
          "color": "secondary"
        },
        {
          "title": "Bulk Import",
          "bullets": ["CSV, JSON, XML", "Validation preview", "Async processing"],
          "color": "tertiary"
        }
      ],
      "variant": "dark",
      "notes": "Deeper dive on the three headline features."
    },
    {
      "type": "highlight",
      "title": "Key Insight",
      "highlight": "Teams using the analytics dashboard resolve incidents 2.4x faster than teams using manual monitoring.",
      "context": "Based on analysis of 180 incidents across 45 teams during August-September. The effect is strongest for teams with 3+ custom dashboard widgets configured.",
      "accentColor": "accent",
      "variant": "light",
      "notes": "This is our strongest product-market signal this quarter."
    },
    {
      "type": "timeline",
      "title": "Q4 Roadmap",
      "milestones": [
        { "label": "OCT", "description": "Advanced filtering and saved views" },
        { "label": "NOV", "description": "Webhook integrations and event streaming" },
        { "label": "DEC", "description": "SOC 2 Type II certification complete" },
        { "label": "JAN", "description": "Public API v2 general availability" }
      ],
      "variant": "light",
      "notes": "Four milestones across the quarter. SOC 2 is the compliance gate for enterprise expansion."
    },
    {
      "type": "closing",
      "notes": "Thank you. Questions?"
    }
  ]
}

What This Deck Demonstrates

• Line break control: Title slide uses \n to split "Q3 Product" and "Update" onto separate lines for deliberate text wrapping
• Section dividers: The section slide creates a clear visual break before the metrics block, signaling a topic change to the audience
• Single vs comparative metrics: stat spotlights one number (CSAT score) while dual_stat places two numbers side-by-side for direct comparison (Q2 vs Q3 revenue)
• Parallel structure: three_card gives equal visual weight to three shipped features, avoiding the implicit ranking that a bullet list creates
• Highlight restraint: highlight is used exactly once for the strongest finding -- overuse dilutes its impact
• Chronological milestones: timeline presents Q4 roadmap items in calendar order, making sequencing and dependencies visible
• Speaker notes on every slide: Notes provide presenter context without cluttering the slide surface -- especially useful for stakeholder decks that get forwarded without the presenter
• Dark/light rhythm: Variants alternate to maintain visual energy; the consecutive light slides (7-8) work because highlight and timeline have distinct visual structures
• Character-limit compliance: All content respects the limits defined in slide-types.md -- titles stay concise, bullets stay scannable, and the highlight sentence remains under the maximum length

Platform Rules

pptxgenjs technical requirements and Google Slides compatibility constraints. Violating these rules produces corrupted files or broken rendering.

pptxgenjs Rules (Mandatory)

1. Never use `#` in hex colors. Write "2563EB", not "#2563EB". The generation engine handles this internally, but raw pptxgenjs code with # causes silent corruption.

2. Never encode opacity in hex strings. Write { color: "000000", opacity: 0.12 }, not "00000020". Eight-character hex with alpha channel is not supported.

3. Never reuse option objects across addShape/addText calls. pptxgenjs mutates option objects internally. Always create fresh objects for each call.

4. Use `bullet: true` for bullet points. Never use unicode bullet characters like \u2022 - that creates double bullets.

5. Use `breakLine: true` between items in text arrays to force line breaks between entries.

6. Each presentation needs `new pptxgen()`. Never reuse a presentation instance across files or generation runs.

Google Slides Compatibility

The default theme deliberately avoids features that degrade in .pptx-to-Google-Slides conversion:

What works reliably across platforms:

• Solid color fills
• Google Fonts (the default theme uses Lexend Deca)
• Simple shapes (rectangles, circles, lines)
• Text boxes with formatting
• Tables with cell formatting
• Speaker notes

Expected after conversion: Minor 1-2 pixel spacing differences are normal and do not affect readability or layout integrity.

Output Format

• File format: .pptx (Office Open XML Presentation)
• Layout: LAYOUT_16x9 (10" x 5.625")
• Output directory: output-slideshow-creator/ by default (gitignored). Override with --output <dir>.
• Naming: From outputFileName in spec, or slugified title, or deck.pptx

PDF Export (Optional)

PDF rendering uses Puppeteer (headless Chromium) with the theme font loaded from Google Fonts. It reads the same JSON spec as the .pptx engine, so both outputs match.

node scripts/export-pdf.mjs deck-spec.json output.pdf

If no output path is given, the PDF is written alongside the spec file. Puppeteer is an optional dependency - the .pptx generation works without it.

Node.js Requirements

• Minimum: Node.js 18
• Dependencies: pptxgenjs (bundled or installed via npm)
• Optional: Puppeteer (for PDF export only)
• Run from any directory; output path is relative to CWD

Slide Types

All 18 slide types with content slots, character limits, and variant support. Each type maps to a JSON type key used in the deck spec.

Variant Support

15 types support variant: "dark" and variant: "light". 3 types are fixed: title_dark (dark only), title_light (light only), closing (dark only).

Type Reference

1. title_dark

Opening slide with dark background and large white title text.

Variant: dark only.

2. title_light

Opening slide with light background for a softer tone.

Variant: light only. Use for internal decks or lighter tone.

3. section

Section divider between major topics. Dark uses two-tone split; light uses clean background.

Variant: "dark" (default) or "light".

4. content

Paragraph content slide for detailed explanations.

Variant: "light" (default) or "dark".

5. bullets

Bullet list slide for key points.

Variant: "light" (default) or "dark".

6. two_col

Two-column comparison layout with vertical divider.

Variant: "light" (default) or "dark".

7. stat

Single statistic displayed on a colored card.

Variant: "light" (default) or "dark".

8. dual_stat

Two stat cards side by side for comparative metrics.

Variant: "dark" (default) or "light".

Use instead of stat when two metrics gain meaning from comparison.

9. quote

Testimonial slide with decorative quote marks and attribution line.

Variant: "dark" (default) or "light".

10. three_card

Three colored cards, each with a title and bullet list.

Variant: "dark" (default) or "light".

11. four_grid

2x2 grid of colored cards, each with a title and body paragraph.

Variant: "dark" (default) or "light".

12. timeline

Horizontal timeline with dots and labels for milestones.

Variant: "light" (default) or "dark".

13. process_flow

Numbered circles connected by lines showing a sequential workflow.

Variant: "light" (default) or "dark".

Use instead of timeline when content is a workflow (action-oriented) rather than dates.

14. agenda

Meeting agenda with a timeline panel on the right side.

Variant: "light" (default) or "dark".

15. highlight

Key takeaway displayed in a prominent colored box with supporting context below.

Variant: "light" (default) or "dark".

Use sparingly -- 1-2 per deck for impact.

16. table

Styled data table with colored header row.

Variant: "light" (default) or "dark".

Best practice: 3-6 columns, 4-8 rows.

17. icon_rows

Feature rows with colored circle markers for visual distinction.

Variant: "light" (default) or "dark".

Use instead of bullets when each point deserves its own visual identity.

18. closing

End slide with dark background.

Variant: dark only.

Common Fields

All slide types accept these optional fields:

• variant -- "dark" or "light" (see defaults above)
• notes -- Speaker notes for presenter view (string, no character limit)
• footer -- Override the deck-level footer text for this slide
• slideNum -- Override the auto-incremented slide number

Color Values

Color fields (accentColor, leftColor, rightColor, card/item color) accept:

• Theme token names: "accent", "secondary", "tertiary", "warm", "primary", "primaryDark", "muted"
• 6-character hex strings: "2563EB", "0891B2" (no # prefix -- pptxgenjs requirement)

JSON Deck Specification Template

<!-- Use this template as a starting point for your deck specification. Fill in the content fields, respecting the character limits documented in slide-types.md. -->

Deck Metadata

{
  "title": "",
  "author": "",
  "footerText": "",
  "outputFileName": "",
  "slides": []
}

Field Reference

Slide Object Structure

Every slide object has type (required) plus content slots defined in slide-types.md.

Common Optional Fields

Color Values

Color fields (accentColor, leftColor, rightColor, card/item color) accept:

• Theme token names: "accent", "secondary", "tertiary", "warm", "primary", "primaryDark", "muted"
• 6-character hex strings: "2563EB", "0891B2" (no # prefix)

Slide Type Quick Reference

See slide-types.md for character limits and detailed slot definitions.