with one click
pptx-generator
// PPTX presentation generation with visual QA: slides, pitch decks.
// PPTX presentation generation with visual QA: slides, pitch decks.
[HINT] Download the complete skill directory including SKILL.md and all related files
| 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"} |
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.
| 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. |
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:
Step 2: Extract content
If the user provides source material (document, outline, notes, article):
If no source material is provided:
If the user provides an existing .pptx as a template:
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.
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:
Step 3: Produce the slide map
Create a JSON array where each element represents one slide. Supported types and their required fields:
title: title, subtitlecontent: title, bullets (list of strings, max 6, max 10 words each)two_column: title, left (header + bullets), right (header + bullets)quote: quote, attributiontable: title, headers, rowssection: titleclosing: title, subtitleSee
references/slide-layouts.mdfor full JSON examples for each layout type.
Step 4: Validate the slide map against anti-AI rules
Before presenting to the user, check:
content)See
references/anti-ai-slide-rules.mdfor 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.
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.mdfor 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:
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.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.
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:
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.
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.mdfor 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.
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:
./presentation.pptx or ./[topic-slug].pptxStep 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.mdfor 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.)
See
references/error-handling.mdfor 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 Pillowtype field on every slide objectreferences/design-system.md -- color palettes with hex codes, typography rules, spacing guidelinesreferences/slide-layouts.md -- 8 layout types with JSON examples, positioning specs, and rhythm guidelinesreferences/anti-ai-slide-rules.md -- 10 patterns to avoid, detection criteria, and the summary checklistreferences/qa-checklist.md -- visual QA criteria for the subagent, severity levels, and output formatreferences/script-reference.md -- CLI arguments, design config format, and exit codes for all three scriptsreferences/dependencies.md -- required and optional packages with install commandsreferences/examples.md -- three worked examples (tech talk, pitch deck, status update)skills/workflow/references/research-to-article.md -- research output can feed slide contentskills/content/gemini-image-generator/SKILL.md -- generate images for slides