PPTX

PPTX Presentation Skill

Create professional PowerPoint presentations using PptxGenJS for all slide generation and media-plugin for sourcing/generating images at correct dimensions.

Before you start: plan the visuals

If you are deciding the deck's visuals yourself (a pitch/sales deck that "should look good"), run the visual-planning skill (media-plugin) FIRST. It decides which concepts deserve a visual, picks the right technique for each, and binds them to one style — then routes each to the correct engine. Skipping it is the main cause of ugly decks.

Routing rule (no exceptions): diagrams, charts, architecture, flows, and data viz go to the graph-generation skill (D3 / Mermaid / Draw.io) and are embedded as PNG. They are never produced via AI generate_image, which mangles labels and layout. AI image generation is only for photos, illustrations, backgrounds, and mockups.

Quick Reference

Setup

# Install dependencies (first time only)
npm install -g pptxgenjs react react-dom react-icons sharp
pip install "markitdown[pptx]" Pillow --break-system-packages

# Verify LibreOffice is available
which soffice || echo "LibreOffice not installed — install with: sudo apt install libreoffice"

# Verify pdftoppm is available
which pdftoppm || echo "pdftoppm not installed — install with: sudo apt install poppler-utils"

If LibreOffice or poppler-utils are not installed, tell the user they are needed for visual QA and ask if they'd like to install them. If the user declines or installation is not possible, skip visual QA and rely on structural checks.

Creating from Scratch

Step 1: Structure

Define the high-level narrative arc. What story does this deck tell? Output: an ordered list of slide titles and their purpose.

Example:

1. Slide 1: Title — hook the audience
2. Slide 2: Problem — establish the pain point
3. Slide 3: Solution — introduce our approach
4. Slide 4: Key Metrics — prove traction
5. ...

This step is about the skeleton — no content details yet.

Step 2: Select a Design Template

Before choosing colors and fonts individually, select a design template from references/templates.md that matches the presentation's purpose. The template provides a complete, pre-tested design system: palette, fonts, motif, rhythm, and background strategy.

Available templates: Pitch Deck, Corporate Quarterly, Tech/Product, Educational/Workshop, Creative/Portfolio, Minimalist Executive, Bold Marketing.

Step 3: Content + Visual Plan

For each slide in the structure, define:

1. Text content — title, subtitle, bullet points, quotes, data points
2. Layout type — pick from the layout catalog (see references/layouts.md)
3. Visual plan — which slides need a visual, and what kind:
   • Data, processes, or system structure → a chart/diagram via graph-generation (D3/Mermaid/Draw.io), embedded as PNG
   • Photos, illustrations, backgrounds → image-sourcing (real) or image-generation (custom)
   • At what aspect ratio (see Image Sizing Rules)
4. Colors + Fonts — use the design template's recommendations, or customize from references/design.md

Vary slide layouts. Monotonous decks with the same layout repeated are the most common failure. Use at least 3 different layout types across a deck.

Design Quality Target

Read references/design.md for the full design system. Key requirements:

• Follow your chosen design template from references/templates.md — don't pick colors/fonts/layouts independently
• At least 2-3 slides with full-bleed photo backgrounds + dark overlay
• Pick ONE visual motif and apply it consistently (color-block headers, side accent strip, generous whitespace, etc.)
• Never combine multiple motifs — no decorative circles AND accent bars AND colored headers on the same deck
• Elevated rounded cards with varied shadow intensity (stronger for primary, subtle for secondary)
• Never more than 2 consecutive plain-background slides
• Dramatic size contrast — titles at 36-48pt, stat numbers at 64-96pt, not timid 28pt and 48pt
• Topic-specific images — prefer real photos from Unsplash; only AI-generate when no suitable stock photo exists
• Use charSpacing: 4-8 on uppercase headers for a premium, editorial feel

Step 4: Gather Images

Gather all planned images BEFORE writing any code. This avoids mid-script interruptions.

For each photo/illustration in the plan:

1. Try Unsplash first — use the image-sourcing skill to search for a real photo. Specify the target aspect ratio (e.g., 16:9 for full-bleed backgrounds, 9:10 for split-image layouts).
2. Fall back to AI generation — if no suitable stock photo exists, use the image-generation skill. Include the target aspect ratio in the generation parameters.
3. Save with descriptive names — e.g., title-bg-cityscape.jpg, split-solar-farm.jpg

For each chart/diagram in the plan:

1. Use the graph-generation skill — D3 for data charts, Mermaid for flows, Draw.io for architecture with vendor icons. Render to high-DPI PNG, theme-matched to the deck's palette.
2. Never AI-generate a chart or diagram via generate_image — it produces fake labels and broken layout.

Always match the image aspect ratio to its placement dimensions. See Image Sizing Rules.

Step 5: Generate PPTX

Read references/pptxgenjs-api.md for the full PptxGenJS API reference and references/layouts.md for slide layout implementations.

Write a Node.js script that generates the .pptx using PptxGenJS:

const pptxgen = require("pptxgenjs");
const fs = require("fs");

async function main() {
  const pres = new pptxgen();
  pres.layout = "LAYOUT_16x9"; // 10" x 5.625"
  pres.author = "Claude";
  pres.title = "Presentation Title";

  // --- Slide 1: Title with photo background ---
  const slide1 = pres.addSlide();
  const bgData = fs.readFileSync("title-bg.jpg");
  slide1.background = { data: "image/jpeg;base64," + bgData.toString("base64") };

  // Dark overlay
  slide1.addShape(pres.shapes.RECTANGLE, {
    x: 0, y: 0, w: 10, h: 5.625,
    fill: { color: "000000", transparency: 45 }
  });

  slide1.addText("Presentation Title", {
    x: 0.8, y: 1.5, w: 8.4, h: 1.5,
    fontSize: 44, fontFace: "Georgia", color: "FFFFFF",
    bold: true, align: "left"
  });

  // --- Add more slides using layout functions from layouts.md ---

  await pres.writeFile({ fileName: "output.pptx" });
  console.log("Done: output.pptx");
}

main().catch(console.error);

Use the layout functions from references/layouts.md — copy the relevant functions into your script and call them with your content.

Critical Rules (violating these corrupts the PPTX file)

• NEVER use # prefix on hex colors — "FF0000" not "#FF0000"
• NEVER encode opacity in hex strings — use the opacity property instead
• NEVER reuse option objects across multiple addShape/addText calls — PptxGenJS mutates them in place. Use factory functions instead.
• Use bullet: true, never unicode bullet characters
• Use breakLine: true between text array items

Step 6: QA

After generating the .pptx, verify it with a rigorous QA process.

5a: Visual QA (thumbnail subagent)

Generate thumbnails and visually inspect via a subagent:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/pptx/scripts/thumbnail.py output.pptx thumbnails

Then launch a subagent to inspect the generated slide images. The subagent should read each thumbnails-N.jpg grid and check for:

• Text overflowing its box or cut off at edges
• Low contrast (light text on light background, dark on dark)
• Uneven spacing or misaligned elements
• Elements too close to slide edges (< 0.5" margins)
• Inconsistent styling between slides
• Images distorted or poorly positioned
• Missing content or placeholder text

5b: Schema Validation

Validate the PPTX against OOXML XSD schemas to catch XML corruption:

python3 ${CLAUDE_PLUGIN_ROOT}/scripts/office/validate.py output.pptx -v

If validation fails, use --auto-repair to fix common issues automatically, or inspect the errors and fix the generation script.

5c: Structural QA

Check for placeholder text and structural issues:

# Extract all text content
python -m markitdown output.pptx

Review the output for:

• Missing text or wrong slide order
• Placeholder text left in (e.g., "Lorem ipsum", "TODO", "Insert text here")
• Typos
• Data accuracy

5d: Placeholder Grep

Search for common placeholder patterns that should never appear in final output:

python -m markitdown output.pptx | grep -iE "(lorem|ipsum|placeholder|todo|tbd|insert|example|sample text)"

If any matches are found, fix the content and regenerate.

Step 7: Fix & Re-verify

If QA reveals issues:

1. Fix the generation script
2. Re-run to generate a new .pptx
3. Re-run QA (Step 5)
4. Repeat until clean

Editing from Template

For editing existing PPTX templates (updating content, adding/removing slides, preserving branding), see editing.md.

Reading Content

To extract text content from an existing PPTX:

python -m markitdown output.pptx

To generate visual thumbnails:

python3 ${CLAUDE_PLUGIN_ROOT}/skills/pptx/scripts/thumbnail.py input.pptx thumbnails/

Image Sizing Rules

When using images (sourced or AI-generated) in the presentation, always match the image aspect ratio to its placement dimensions on the slide. Mismatched aspect ratios cause distortion.

Common placement sizes and their aspect ratios

Rules

• NEVER generate all images at 16:9 by default — only use 16:9 for full-bleed backgrounds
• Use sizing: { type: "cover", w: W, h: H } on every addImage call so images fill their box without distortion
• If the exact ratio doesn't match a standard option, pick the closest standard aspect ratio (1:1, 4:3, 3:2, 16:9, 9:16, etc.)
• For AI-generated images, include the target aspect ratio in the generation prompt/parameters

Design Ideas

See references/templates.md for 7 topic-aware design templates — complete presets for palette, fonts, motif, and rhythm.

See references/design.md for:

• Color palettes (22 curated palettes including modern dark themes)
• Dark theme design system with contrast rules
• Font pairings organized by personality (25+ options)
• Typography as design element (hero numbers, charSpacing, impact words)
• Visual motif system (pick ONE per deck)
• Depth and layering techniques
• Deck rhythm principles
• Common design mistakes to avoid

QA

See Step 6 above for the full QA process. Key points:

• Always generate thumbnails via thumbnail.py and visually inspect
• Use a subagent for visual inspection — it can read the slide images and check for issues
• Always run structural QA via markitdown to catch missing/wrong text
• Grep for placeholders to catch any template text left in
• Fix and re-verify until clean — never ship a deck without QA

Scripts

Shared Office Scripts

PPTX-Specific Scripts

Reference Files

Read templates.md first (to pick a design system), then design.md and layouts.md before generating any presentation.