pptx-generator

name	pptx-generator
description	PPTX presentation generation with visual QA: slides, pitch decks.
user-invocable	false
allowed-tools	["Read","Write","Bash","Grep","Glob","Edit","Task"]
routing	{"triggers":["presentation","powerpoint","pptx","slide deck","pitch deck","slides","create slides","generate presentation","make a deck","conference talk slides"],"pairs_with":["workflow","gemini-image-generator"],"complexity":"Medium-Complex","category":"content-generation"}

PPTX Presentation Generator

Overview

This skill generates polished PowerPoint decks through a 6-phase pipeline that separates content decisions (LLM) from slide construction (deterministic script) from visual validation (fresh-eyes subagent). The core principle: "Slides are visual documents, not text dumps. Generate mechanically, validate visually."

This separation prevents the common failure mode where the generator rationalizes away visual defects it introduced. The visual QA subagent has zero generation context and sees slides as viewers would.

---

Reference Loading Table

Signal	Load These Files	Why
tasks related to this reference	anti-ai-slide-rules.md	Loads detailed guidance from anti-ai-slide-rules.md.
tasks related to this reference	dependencies.md	Loads detailed guidance from dependencies.md.
tasks related to this reference	design-system.md	Loads detailed guidance from design-system.md.
errors, error handling	error-handling.md	Loads detailed guidance from error-handling.md.
example-driven tasks	examples.md	Loads detailed guidance from examples.md.
checklist-driven work	qa-checklist.md	Loads detailed guidance from qa-checklist.md.
tasks related to this reference	script-reference.md	Loads detailed guidance from script-reference.md.
tasks related to this reference	slide-layouts.md	Loads detailed guidance from slide-layouts.md.

Instructions

Phase 1: GATHER

Goal: Collect content, determine presentation structure, identify the presentation type.

Why this phase exists: Jumping straight to slide design without understanding the content produces a generic deck that doesn't serve the audience. Gathering first ensures every slide has a purpose.

Step 1: Parse the user request

Extract from the user's input:

• Topic: What is the presentation about?
• Audience: Who will view it? (executives, engineers, students, general public)
• Tone: Formal, casual, technical, inspirational?
• Slide count: Explicit request or estimate from content volume. Default: 8-12 slides.
• Presentation type: Classify as one of:
  • Pitch deck: Investor/stakeholder persuasion
  • Tech talk: Engineering audience, architecture, code
  • Status update: Progress report, metrics, next steps
  • Educational: Teaching, workshop, tutorial
  • General: Does not fit above categories

Step 2: Extract content

If the user provides source material (document, outline, notes, article):

• Extract key points, data, and quotes
• Organize into logical sections
• Identify content that maps to specific slide types (data -> table, key insight -> quote, comparison -> two-column)

If no source material is provided:

• Work with the user to develop an outline
• Ask clarifying questions about scope and depth

If the user provides an existing .pptx as a template:

• Read it with python-pptx to understand the existing structure
• Plan which slides to modify vs. add

Step 3: Determine slide structure

Based on content volume and presentation type, plan the slide sequence. Follow the layout rhythm guidelines in references/slide-layouts.md:

Deck Size	Rhythm Pattern
Short (5-8)	Title, Content, Content, Two-Column, Content, Closing
Medium (8-12)	Title, Content, Content, Quote, Section, Content, Two-Column, Content, Closing
Long (12+)	Title, Content, Content, Quote, Section, Content, Image+Text, Content, Section, Two-Column, Table, Content, Closing

GATE: Content outline exists with at least 1 key point per planned slide. Presentation type identified. Slide count determined. If the user's content is too thin for the requested slide count, flag this and suggest a smaller deck rather than padding with filler.

---

Phase 2: DESIGN

Goal: Select palette and typography, produce the slide map, get user approval before generation.

Why this phase exists: Design decisions made after generation are expensive -- they require regenerating the entire deck. Making them upfront and getting user approval saves iteration budget for visual fixes, not content rework.

Step 1: Select color palette

Use the palette selection heuristic from references/design-system.md:

Presentation Type	Recommended Palette	Fallback
Business / Finance	Corporate	Minimal
Engineering / Dev talk	Tech	Minimal
Creative / Workshop	Warm	Sunset
Healthcare / Sustainability	Ocean	Forest
Dark theme keynote	Midnight	Tech
Environmental / Nonprofit	Forest	Ocean
Startup / Energy	Sunset	Warm
Unknown / General	Minimal	Corporate

If the user specifies a palette preference, use it. When in doubt, use Minimal.

Step 2: Plan layout rhythm

Select layout types for each slide. Use at least 2-3 distinct layout types to avoid the "AI-generated sameness" anti-pattern. See references/slide-layouts.md for all layout types.

Available layouts: title, section (divider), content (bullets), two_column, image_text, quote (callout), table, closing

Layout rhythm rules:

• Use a different layout after 3 consecutive slides of the same type in a row. (Reason: Identical layouts are the most obvious AI-slide tell. Real presentations have visual rhythm with varied layouts.)
• For 10+ slide decks, use at least 3 distinct layout types
• Insert a different layout type (quote, two-column, section divider) to break repetition

Step 3: Produce the slide map

Create a JSON array where each element represents one slide. Supported types and their required fields:

• title: title, subtitle
• content: title, bullets (list of strings, max 6, max 10 words each)
• two_column: title, left (header + bullets), right (header + bullets)
• quote: quote, attribution
• table: title, headers, rows
• section: title
• closing: title, subtitle

See references/slide-layouts.md for full JSON examples for each layout type.

Step 4: Validate the slide map against anti-AI rules

Before presenting to the user, check:

• At least 2-3 distinct layout types used (not all content)
• No more than 3 consecutive slides with the same layout
• Max 6 bullets per content slide, max 10 words per bullet (Reason: 9 bullets is a document paragraph, not a slide. Readability degrades sharply past 6.)
• Title slide is first, closing slide is last (if appropriate)
• Section dividers placed before new sections (for 8+ slide decks)

See references/anti-ai-slide-rules.md for the full checklist.

Step 5: Present slide map for user approval

Show the user the planned deck structure:

SLIDE MAP (10 slides, Corporate palette):

  1. [Title] "Q4 Revenue Analysis"
  2. [Content] "Executive Summary" (4 bullets)
  3. [Content] "Revenue by Region" (5 bullets)
  4. [Quote] Key insight from CFO
  5. [Section] "Deep Dive: EMEA"
  6. [Two-Column] EMEA vs APAC comparison
  7. [Content] "Contributing Factors" (4 bullets)
  8. [Table] Quarterly figures
  9. [Content] "Recommendations" (3 bullets)
  10. [Closing] "Questions?"

Approve this structure, or suggest changes?

GATE: User approves the slide map. If the user requests changes, update the slide map and re-present. Get explicit user approval before proceeding to generation. Why: regeneration costs iteration budget that should be reserved for visual QA fixes.

---

Phase 3: GENERATE

Goal: Execute the deterministic Python script to produce the .pptx file.

Why this phase exists: Slide construction is mechanical work -- given a slide map and design config, the output is deterministic. This belongs in a script, not in LLM-generated inline code. Scripts are testable, reproducible, and consistent. (Reason: Inline code is not testable, wastes tokens on boilerplate, and risks inconsistency. The script encapsulates palette application, layout selection, font sizing, spacing rules, and all design system constraints.)

Step 1: Check dependencies

python3 -c "from pptx import Presentation; print('python-pptx OK')"

If python-pptx is not installed, install it:

pip install python-pptx Pillow

Step 2: Write the slide map and design config to JSON files

Save the approved slide map and design config to /tmp/slide_map.json and /tmp/design_config.json using python3 -c "import json; ..." with the approved data. Use absolute paths for all file arguments.

See references/script-reference.md for the design config JSON format and a copy-paste template for this step.

Step 3: Run the generation script

python3 /path/to/skills/content/pptx-generator/scripts/generate_pptx.py \
  --slide-map /tmp/slide_map.json \
  --design /tmp/design_config.json \
  --output /absolute/path/to/output.pptx

Exit codes: 0 = success, 1 = missing python-pptx, 2 = invalid input, 3 = generation failed.

Constraints applied during generation:

• Blank Layout Only: Always use slide_layouts[6] (blank) as the base layout. Why: using template-specific layouts (title, content) inherits unpredictable formatting from whatever default template python-pptx ships. Blank gives us full control.
• Safe Fonts Only: Use Calibri and Arial exclusively. Why: presentations are shared documents. Custom fonts cause rendering failures on machines that lack them. Portability trumps aesthetics.
• Widescreen Format: 16:9 (13.333 x 7.5 inches). This is the universal modern presentation format.

Step 4: Run structural validation

python3 /path/to/skills/content/pptx-generator/scripts/validate_structure.py \
  --input /absolute/path/to/output.pptx \
  --slide-map /tmp/slide_map.json

This validates: slide count matches, each slide has text content, title slide exists, no empty slides.

GATE: .pptx file exists with non-zero size AND structural validation passes. If validation fails, diagnose the issue (usually a slide map JSON problem), fix, and re-run. Max 2 retries at this gate before escalating to the user.

---

Phase 4: CONVERT (Requires LibreOffice)

Goal: Convert the .pptx to per-slide PNG images for visual QA.

Why this phase exists: The QA subagent cannot read .pptx files. It needs rendered images to evaluate visual quality -- text clipping, color contrast, alignment, and anti-AI violations are only visible in rendered output.

Step 1: Check LibreOffice availability

soffice --version 2>/dev/null

If LibreOffice is not installed:

• Log: "LibreOffice not available. Skipping visual QA, using structural validation only."
• Skip Phase 5 (QA) and proceed directly to Phase 6 (OUTPUT)
• Note in the output report that visual QA was skipped

Step 2: Run the conversion script

python3 /path/to/skills/content/pptx-generator/scripts/convert_slides.py \
  --input /absolute/path/to/output.pptx \
  --output-dir /tmp/pptx_qa_images/ \
  --dpi 150

Exit codes: 0 = success, 1 = no LibreOffice, 2 = conversion failed, 3 = invalid input.

Step 3: Verify conversion output

Check that one PNG exists per slide. If fewer PNGs than slides, some slides may have failed to render. Note which slides are missing.

GATE: Either (a) one PNG per slide exists, proceed to Phase 5, or (b) LibreOffice unavailable, skip to Phase 6 with a note. If conversion partially fails (some PNGs missing), proceed to QA with available images and note the gaps.

---

Phase 5: QA (Visual Inspection Loop)

Goal: A fresh-eyes subagent inspects the rendered slides and identifies visual issues. Fix and re-render up to 3 times.

Why a subagent: The generating agent has context bias -- it "knows" what the slide should look like and will rationalize visual problems. A fresh-eyes subagent with zero generation context sees the slide as a viewer would.

Why max 3 iterations: If visual issues persist after 3 fix cycles, the design is wrong, not the implementation. Stop iterating after 3 attempts. More iterations burn context without convergence.

Step 1: Dispatch QA subagent

Launch a subagent (via Task tool) with the slide PNG images, the original slide map, and the QA checklist from references/qa-checklist.md. The subagent evaluates text readability, layout alignment, color usage, content accuracy, anti-AI violations, and structural checks.

See references/qa-checklist.md for the full subagent prompt template, all six check categories, severity levels, and expected output format.

Step 2: Process QA results

If QA returns PASS: proceed to Phase 6.

If QA returns FAIL with Blocker or Major issues: parse the fix instructions, modify the slide map JSON to address each issue, re-run Phases 3 and 4, re-dispatch the QA subagent. Minor issues are reported without triggering a fix cycle.

Track iteration count:

QA Iteration 1/3: 2 issues found (1 Blocker, 1 Major)
QA Iteration 2/3: 1 issue found (1 Minor)
QA Iteration 3/3: PASS (0 Blocker, 0 Major)

GATE: QA subagent returns PASS, OR 3 iterations exhausted. If iterations exhausted with remaining issues, include them in the output report.

---

Phase 6: OUTPUT

Goal: Deliver the final .pptx file with a summary report. Clean up intermediate files.

Step 1: Move the final .pptx to the user's working directory

Copy from temp location to a sensible output path:

• If user specified an output path, use it
• Otherwise: ./presentation.pptx or ./[topic-slug].pptx

Step 2: Generate the output report

Print a summary block with: file path, slide count, palette, format (16:9 widescreen), file size, the full slide map, QA result (PASS/FAIL, iterations, issues fixed), and any remaining minor issues.

See references/script-reference.md for the exact output report template.

Step 3: Clean up intermediate files

Remove:

• /tmp/slide_map.json
• /tmp/design_config.json
• /tmp/pptx_qa_images/ directory (PNG renders and PDFs)

Keep only the final .pptx file. (Reason: Cleanup is a default behavior to remove intermediate files after final output.)

---

Error Handling

See references/error-handling.md for full error descriptions, blocker criteria, confirm-with-user list, and retry limits.

Quick reference (the four errors you'll hit most):

• python-pptx missing: pip install python-pptx Pillow
• LibreOffice missing: soft dependency, skip Phases 4-5, note in output report
• Slide map JSON invalid: check type field on every slide object
• QA loop > 3 iterations: stop, report remaining issues, deliver best available version

---

References

• Design System: references/design-system.md -- color palettes with hex codes, typography rules, spacing guidelines
• Slide Layouts: references/slide-layouts.md -- 8 layout types with JSON examples, positioning specs, and rhythm guidelines
• Anti-AI Slide Rules: references/anti-ai-slide-rules.md -- 10 patterns to avoid, detection criteria, and the summary checklist
• QA Checklist: references/qa-checklist.md -- visual QA criteria for the subagent, severity levels, and output format
• Script Reference: references/script-reference.md -- CLI arguments, design config format, and exit codes for all three scripts
• Dependencies: references/dependencies.md -- required and optional packages with install commands
• Examples: references/examples.md -- three worked examples (tech talk, pitch deck, status update)

Complementary Skills

• skills/workflow/references/research-to-article.md -- research output can feed slide content
• skills/content/gemini-image-generator/SKILL.md -- generate images for slides