Pptx

PPTX creation, editing, and analysis

Overview

Create, edit, or analyze the contents of .pptx files when requested. A .pptx file is essentially a ZIP archive containing XML files and other resources. Different tools and workflows are available for different tasks.

Mode Selection Rules

Choose the workflow based on the user's actual artifact and intent:

1. Existing .pptx provided and user asked to edit/revise/update it

• Treat this as an edit-in-place task.
• Preserve the user's current deck, theme, masters, layouts, and speaker notes unless they explicitly ask for redesign.
• Use the editing workflow or template-analysis workflow against their file.
• Do not replace their deck with .claude/skills/pptx/templates/reference.pptx.

1. No existing .pptx provided and user wants a new deck

• Use the best creation path:
• bundled corporate template for branded decks
• html2pptx for non-template bespoke decks

1. Existing .pptx provided and user explicitly asks to rebuild or restyle it into the corporate template

• You may use .claude/skills/pptx/templates/reference.pptx as the target style base.
• Make that transformation explicit in your reasoning and output.

If there is any ambiguity, ask a clarifying question before proceeding:

• do they want edits to the uploaded deck
• or a fresh rebuilt version in the corporate template

Preferred Path For Corporate Decks

For a new branded presentation using the bundled OpenGolem corporate template, use:

• template: .claude/skills/pptx/templates/reference.pptx
• generator: .claude/skills/pptx/scripts/generate_corporate_pptx.py

This is the preferred path when the user wants a polished internal or client-ready deck and does not provide their own PPTX template.

Use layout-driven slide JSON with the following body slide types:

• section
• bullets
• two-column
• quote
• closing

The generator always creates the cover slide from the CLI metadata and then builds the remaining deck from the chosen template slides.

Example:

python3 .claude/skills/pptx/scripts/generate_corporate_pptx.py \
  --title "Nematodes: Executive Overview" \
  --subtitle "Biology, risks, and agricultural impact" \
  --date "April 2026" \
  --classification "INTERNAL" \
  --prepared-by "OpenGolem Research" \
  --output output/nematodes_overview.pptx \
  --slides-json '[
    {"layout":"section","title":"Why Nematodes Matter","kicker":"Context"},
    {"layout":"bullets","title":"Core Facts","bullets":["Nematodes are among the most abundant animals on earth","They occupy soil, marine, freshwater, and host-associated niches","A minority are major crop and health threats"],"footer":"Use one idea per bullet"},
    {"layout":"two-column","title":"Helpful vs Harmful","left_title":"Beneficial roles","left_bullets":["Nutrient cycling","Soil food-web balance"],"right_title":"Major risks","right_bullets":["Plant parasitism","Livestock and human disease"]},
    {"layout":"quote","quote":"Management depends on distinguishing harmless background populations from economically meaningful infestation.","attribution":"Suggested speaker emphasis"},
    {"layout":"closing","title":"Recommended Next Step","bullets":["Define audience-specific storyline","Add visuals only where they clarify the science","Validate every slide visually before delivery"]}
  ]'

Validation after generation:

python3 .claude/skills/pptx/scripts/thumbnail.py output/nematodes_overview.pptx output/nematodes_overview

Prerequisites for the Python-based template workflow:

• python-pptx
• Pillow
• LibreOffice plus pdftoppm if you want thumbnail validation

CRITICAL: Read All Documentation First

Before starting any presentation task, read ALL relevant documentation files completely to understand the full workflow:

1. For creating new presentations: Read [html2pptx.md](html2pptx.md) and [css.md](css.md) in their entirety
2. For editing existing presentations: Read [ooxml.md](ooxml.md) in its entirety
3. For template-based creation: Read the relevant sections of this file plus [css.md](css.md)

NEVER set any range limits when reading these files. Understanding the complete workflow, constraints, and best practices before starting is essential for producing high-quality presentations. Partial knowledge leads to errors, inconsistent styling, and visual defects that require rework.

Reading and analyzing content

Text extraction

To read just the text content of a presentation, convert the document to markdown:

# Convert document to markdown
python3 -m markitdown path-to-file.pptx

Raw XML access

Use raw XML access for: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. To access these features, unpack a presentation and read its raw XML contents.

Unpacking a file

python3 ooxml/scripts/unpack.py

Key file structures

• ppt/presentation.xml - Main presentation metadata and slide references
• ppt/slides/slide{N}.xml - Individual slide contents (slide1.xml, slide2.xml, etc.)
• ppt/notesSlides/notesSlide{N}.xml - Speaker notes for each slide
• ppt/comments/modernComment_*.xml - Comments for specific slides
• ppt/slideLayouts/ - Layout templates for slides
• ppt/slideMasters/ - Master slide templates
• ppt/theme/ - Theme and styling information
• ppt/media/ - Images and other media files

Typography and color extraction

To emulate example designs, analyze the presentation's typography and colors first using the methods below:

1. Read theme file: Check ppt/theme/theme1.xml for colors (`) and fonts (`)
2. Sample slide content: Examine ppt/slides/slide1.xml for actual font usage (``) and colors
3. Search for patterns: Use grep to find color (`, `) and font references across all XML files

Creating a new PowerPoint presentation without a template

When creating a new PowerPoint presentation from scratch, use the html2pptx workflow to convert HTML slides to PowerPoint with accurate positioning.

Workflow

1. Read documentation: Read [html2pptx.md](html2pptx.md) and [css.md](css.md) completely (see "CRITICAL: Read All Documentation First" section above)

1. PREREQUISITE - Extract html2pptx library:

• Extract the library next to your script: mkdir -p html2pptx && tar -xzf html2pptx.tgz -C html2pptx
• This creates a html2pptx/ directory with the library files and CLI binaries

1. Plan the presentation: Follow html2pptx.md "Design Philosophy" section for:

• Aesthetic direction and bold design choices
• Color palette selection (see "Creating your color palette")
• Typography strategy
• Write DETAILED outline with slide layouts and presenter notes (1-3 sentences per slide)

1. Set CSS variables: Override CSS variables in a shared .css file for colors, typography, and spacing (see css.md "Design System Variables")

1. Create HTML slides (960px × 540px for 16:9): Follow html2pptx.md for:

• Slide layout zones (title, content, footnote)
• Critical text rules (proper HTML tags)
• Supported elements and styling

1. Create and run a JavaScript file using the [html2pptx](./html2pptx) library to convert HTML slides to PowerPoint and save the presentation

• Run with: NODE_PATH="$(npm root -g)" node your-script.js 2>&1
• Use the html2pptx function to process each HTML file
• Add charts and tables to placeholder areas using PptxGenJS API
• Save the presentation using pptx.writeFile()

• ⚠️ CRITICAL: Your script MUST follow this example structure. Think aloud before writing the script to make sure that you correctly use the APIs. Do NOT call pptx.addSlide.

```javascript const pptxgen = require("pptxgenjs"); const { html2pptx } = require("./html2pptx");

// Create a new pptx presentation const pptx = new pptxgen(); pptx.layout = "LAYOUT_16x9"; // Must match HTML body dimensions

// Add an HTML-only slide await html2pptx("slide1.html", pptx);

// Add a HTML slide with chart placeholders const { slide: slide2, placeholders } = await html2pptx("slide2.html", pptx); slide.addChart(pptx.charts.LINE, chartData, placeholders[0]);

// Save the presentation await pptx.writeFile("output.pptx"); ```

1. Visual validation: Convert to images and inspect for layout issues

• Convert PPTX to PDF first: soffice --headless --convert-to pdf output.pptx
• Then convert PDF to images: pdftoppm -jpeg -r 150 output.pdf slide
• This creates files like slide-1.jpg, slide-2.jpg, etc.
• Read each generated image file and carefully examine for:
• Text cutoff: Text being cut off by header bars, shapes, or slide edges
• Text overlap: Text overlapping with other text or shapes
• Positioning issues: Content too close to slide boundaries or other elements
• Contrast issues: Insufficient contrast between text and backgrounds
• Alignment problems: Elements not properly aligned with each other
• Visual hierarchy: Important content properly emphasized
• CRITICAL: All slides MUST pass these validation checks before delivering to the user. Do not skip this step or deliver presentations with visual defects.
• If issues found, fix them in the following order of priority:

1. Increase margins - Add more padding/spacing around problematic elements
2. Adjust font size - Reduce text size to fit within available space
3. Rethink the layout entirely - If the above fixes don't work, redesign the slide layout

• Regenerate the presentation after making changes
• Repeat until all slides are visually correct

Editing an existing PowerPoint presentation

To edit slides in an existing PowerPoint presentation, work with the raw Office Open XML (OOXML) format. This involves unpacking the .pptx file, editing the XML content, and repacking it.

This is the default workflow whenever the user supplied an existing presentation and asked for modifications, unless they explicitly asked for a rebuild into another template or design system.

Workflow

1. Read documentation: Read [ooxml.md](ooxml.md) completely (see "CRITICAL: Read All Documentation First" section above)
2. Unpack the presentation: python3 ooxml/scripts/unpack.py
3. Edit the XML files (primarily ppt/slides/slide{N}.xml and related files)
4. CRITICAL: Validate immediately after each edit: python3 ooxml/scripts/validate.py --original
5. Pack the final presentation: python3 ooxml/scripts/pack.py

Creating a new PowerPoint presentation using a template

To create a presentation that follows an existing template's design, duplicate and re-arrange template slides before replacing placeholder content.

Workflow

1. Extract template text AND create visual thumbnail grid:

• Extract text: python3 -m markitdown template.pptx > template-content.md
• Read template-content.md completely to understand the template contents
• Create thumbnail grids: python3 scripts/thumbnail.py template.pptx
• See [Creating Thumbnail Grids](#creating-thumbnail-grids) section for more details

1. Analyze template and save inventory to a file:

• Visual Analysis: Review thumbnail grid(s) to understand slide layouts, design patterns, and visual structure
• Create and save a template inventory file at template-inventory.md containing:

```markdown # Template Inventory Analysis

Total Slides: [count] IMPORTANT: Slides are 0-indexed (first slide = 0, last slide = count-1)

## [Category Name]

• Slide 0: [Layout code if available] - Description/purpose
• Slide 1: [Layout code] - Description/purpose
• Slide 2: [Layout code] - Description/purpose

[... EVERY slide must be listed individually with its index ...] ```

• Using the thumbnail grid: Reference the visual thumbnails to identify:
• Layout patterns (title slides, content layouts, section dividers)
• Image placeholder locations and counts
• Design consistency across slide groups
• Visual hierarchy and structure
• This inventory file is REQUIRED for selecting appropriate templates in the next step

1. Create presentation outline based on template inventory:

• Review available templates from step 2.
• Choose an intro or title template for the first slide. This should be one of the first templates.
• Choose safe, text-based layouts for the other slides.
• CRITICAL: Match layout structure to actual content:
• Single-column layouts: Use for unified narrative or single topic
• Two-column layouts: Use ONLY when there are exactly 2 distinct items/concepts
• Three-column layouts: Use ONLY when there are exactly 3 distinct items/concepts
• Image + text layouts: Use ONLY when there are actual images to insert
• Quote layouts: Use ONLY for actual quotes from people (with attribution), never for emphasis
• Never use layouts with more placeholders than available content
• With 2 items, avoid forcing them into a 3-column layout
• With 4+ items, consider breaking into multiple slides or using a list format
• Count actual content pieces BEFORE selecting the layout
• Verify each placeholder in the chosen layout will be filled with meaningful content
• Select one option representing the best layout for each content section.
• Save outline.md with content AND template mapping that leverages available designs
• Example template mapping:

`` # Template slides to use (0-based indexing) # WARNING: Verify indices are within range! Template with 73 slides has indices 0-72 # Mapping: slide numbers from outline -> template slide indices template_mapping = [ 0, # Use slide 0 (Title/Cover) 34, # Use slide 34 (B1: Title and body) 34, # Use slide 34 again (duplicate for second B1) 50, # Use slide 50 (E1: Quote) 54, # Use slide 54 (F2: Closing + Text) ] ``

1. Duplicate, reorder, and delete slides using rearrange.py:

• Use the scripts/rearrange.py script to create a new presentation with slides in the desired order:

``bash python3 scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52 ``

• The script handles duplicating repeated slides, deleting unused slides, and reordering automatically
• Slide indices are 0-based (first slide is 0, second is 1, etc.)
• The same slide index can appear multiple times to duplicate that slide

1. Extract ALL text using the inventory.py script:

• Run inventory extraction:

``bash python3 scripts/inventory.py working.pptx text-inventory.json ``

• Read text-inventory.json completely to understand all shapes and their properties

• The inventory JSON structure:

```json { "slide-0": { "shape-0": { "placeholdertype": "TITLE", // or null for non-placeholders "left": 1.5, // position in inches "top": 2.0, "width": 7.5, "height": 1.2, "paragraphs": [ { "text": "Paragraph text", // Optional properties (only included when non-default): "bullet": true, // explicit bullet detected "level": 0, // only included when bullet is true "alignment": "CENTER", // CENTER, RIGHT (not LEFT) "spacebefore": 10.0, // space before paragraph in points "spaceafter": 6.0, // space after paragraph in points "linespacing": 22.4, // line spacing in points "fontname": "Arial", // from first run "fontsize": 14.0, // in points "bold": true, "italic": fal

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: luckeyfaraday
• Source: luckeyfaraday/OpenGolem
• License: MIT
• Homepage: https://opengolem.netlify.app/

Install and usage instructions live in the source repository linked above.