PPTX Creation, Editing, and Analysis

Overview

Users may ask you to create, edit, or analyze the content of .pptx files. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. Different tasks have different available tools and workflows.

Reading and Analyzing Content

Text Extraction

If you only need to read the text content of a presentation, convert the document to markdown:

bash

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

Raw XML Access

You need raw XML access to handle: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. For these features, you need to unpack the presentation and read its raw XML content.

Unpacking Files

python ooxml/scripts/unpack.py <office_file> <output_dir>

Note: The unpack.py script is located at

skills/pptx/ooxml/scripts/unpack.py

relative to the project root. If the script is not in this path, use

find . -name "unpack.py"

to locate it.

Key File Structure

```
ppt/presentation.xml
```
- Main presentation metadata and slide references
```
ppt/slides/slide{N}.xml
```
- Individual slide content (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/
```
- Slide layout templates
```
ppt/slideMasters/
```
- Master slide templates
```
ppt/theme/
```
- Theme and style information
```
ppt/media/
```
- Images and other media files

Typography and Color Extraction

When provided with a sample design to mimic: Always first analyze the presentation's typography and colors using the following methods:

Read theme files: Check colors (
```
<a:clrScheme>
```
) and fonts (
```
<a:fontScheme>
```
) in
```
ppt/theme/theme1.xml
```
Sample slide content: Check actual font usage (
```
<a:rPr>
```
) and colors in
```
ppt/slides/slide1.xml
```
Search for patterns: Use grep to find color (
```
<a:solidFill>
```
,
```
<a:srgbClr>
```
) and font references in all XML files

Creating New PowerPoint Presentations Without Templates

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

Design Principles

Key: Before creating any presentation, analyze the content and select appropriate design elements:

Consider the theme: What is this presentation about? What tone, industry, or mood does it imply?
Check branding: If the user mentions a company/organization, consider its brand colors and image
Match color palette to content: Choose colors that reflect the theme
Explain your approach: Explain your design choices before writing code

Requirements:

✅ Explain your content-based design approach before writing code
✅ Only use web-safe fonts: Arial, Helvetica, Times New Roman, Georgia, Courier New, Verdana, Tahoma, Trebuchet MS, Impact
✅ Create clear visual hierarchy through size, weight, and color
✅ Ensure readability: strong contrast, appropriately sized text, neat alignment
✅ Maintain consistency: repeat patterns, spacing, and visual language across slides

Color Palette Selection

Choose colors creatively:

Think beyond defaults: What colors truly match this specific theme? Avoid automatic selection.
Consider multiple angles: theme, industry, mood, energy level, target audience, brand image (if mentioned)
Be bold: Try unexpected combinations - healthcare presentations don't have to be green, finance doesn't have to be navy blue
Build a palette: Choose 3-5 colors that work well together (primary + secondary + accent colors)
Ensure contrast: Text must be clearly readable against the background

Sample Palettes (for inspiration - choose one, adjust it, or create your own):

Classic Blue: Deep Navy (#1C2833), Slate Gray (#2E4053), Silver (#AAB7B8), Off-White (#F4F6F6)
Teal & Coral: Teal (#5EA8A7), Deep Teal (#277884), Coral (#FE4447), White (#FFFFFF)
Bold Red: Red (#C0392B), Bright Red (#E74C3C), Orange (#F39C12), Yellow (#F1C40F), Green (#2ECC71)
Warm Blush: Taupe (#A49393), Blush (#EED6D3), Rose (#E8B4B8), Cream (#FAF7F2)
Burgundy Luxury: Burgundy (#5D1D2E), Deep Red (#951233), Rust (#C15937), Gold (#997929)
Deep Purple & Emerald: Purple (#B165FB), Dark Blue (#181B24), Emerald (#40695B), White (#FFFFFF)
Cream & Forest Green: Cream (#FFE1C7), Forest Green (#40695B), White (#FCFCFC)
Pink & Purple: Pink (#F8275B), Coral (#FF574A), Rose (#FF737D), Purple (#3D2F68)
Lime & Plum: Lime (#C5DE82), Plum (#7C3A5F), Coral (#FD8C6E), Slate Blue (#98ACB5)
Black & Gold: Gold (#BF9A4A), Black (#000000), Cream (#F4F6F6)
Sage & Terracotta: Sage (#87A96B), Terracotta (#E07A5F), Cream (#F4F1DE), Charcoal (#2C2C2C)
Charcoal & Red: Charcoal (#292929), Red (#E33737), Light Gray (#CCCBCB)
Vibrant Orange: Orange (#F96D00), Light Gray (#F2F2F2), Charcoal (#222831)
Forest Green: Black (#191A19), Green (#4E9F3D), Deep Green (#1E5128), White (#FFFFFF)
Vintage Rainbow: Purple (#722880), Pink (#D72D51), Orange (#EB5C18), Amber (#F08800), Gold (#DEB600)
Vintage Earth: Mustard (#E3B448), Sage (#CBD18F), Forest Green (#3A6B35), Cream (#F4F1DE)
Coastal Rose: Old Rose (#AD7670), Beaver (#B49886), Eggshell (#F3ECDC), Gray Green (#BFD5BE)
Orange & Teal: Light Orange (#FC993E), Gray Teal (#667C6F), White (#FCFCFC)

Visual Detail Options

Geometric Patterns:

Diagonal separators instead of horizontal separators
Asymmetric column widths (30/70, 40/60, 25/75)
Text titles rotated 90° or 270°
Circular/hexagonal frames for images
Triangle decorative shapes in corners
Overlapping shapes to add depth

Border and Frame Treatments:

Thick solid border on only one side (10-20pt)
Double-line border with contrasting colors
Angle brackets instead of full frames
L-shaped borders (top+left or bottom+right)
Underline emphasis below titles (3-5pt thick)

Typography Treatments:

Extreme size contrast (72pt title vs 11pt body text)
Uppercase titles with wide letter spacing
Oversized display font for numbered sections
Monospace font (Courier New) for data/statistics/technical content
Narrow font (Arial Narrow) for dense information
Outline text for emphasis

Chart and Data Styles:

Monochrome charts with single accent color for key data
Horizontal bar charts instead of vertical bar charts
Dot plots instead of bar charts
Minimal or no grid lines
Data labels directly on elements (no legend)
Oversized numbers for key metrics

Layout Innovations:

Full-page images with text overlays
Sidebar columns (20-30% width) for navigation/context
Modular grid systems (3×3, 4×4 blocks)
Z-shaped or F-shaped content flow
Floating text boxes over colored shapes
Magazine-style multi-column layouts

Background Treatments:

Solid color blocks covering 40-60% of the slide
Gradient fills (only vertical or diagonal)
Split backgrounds (two colors, diagonal or vertical)
Edge-to-edge color bands
Negative space as a design element

Layout Tips

When creating slides with charts or tables:

Two-column layout (recommended): Use a full-width title, then two columns below - one for text/bullets, the other for main content. This provides better balance and makes charts/tables more readable. Use flexbox with unequal column widths (e.g., 40%/60% split) to optimize space for each content type.
Full-slide layout: Let main content (charts/tables) occupy the entire slide for maximum impact and readability
Never stack vertically: Do not place charts/tables below text in a single column - this causes poor readability and layout issues

Workflow

Mandatory - Read the entire file completely: Read
```
html2pptx.md
```
from start to finish. Do not set any scope limits when reading this file. Before starting to create the presentation, read the complete file content to understand detailed syntax, key formatting rules, and best practices.
Create HTML files with correct dimensions for each slide (e.g., 720pt × 405pt for 16:9)
- Use
```
<p>
```
  ,
```
<h1>
```
  -
```
<h6>
```
  ,
```
<ul>
```
  ,
```
<ol>
```
  for all text content
- Use
```
class="placeholder"
```
  for areas where charts/tables will be added (renders gray background for visibility)
- Key: First rasterize gradients and icons to PNG images using Sharp, then reference them in HTML
- Layout: For slides with charts/tables/images, use full-slide layout or two-column layout for better readability
Create and run a JavaScript file using the
```
html2pptx.js
```
library to convert HTML slides to PowerPoint and save the presentation
- Use the
```
html2pptx()
```
  function to process each HTML file
- Use the PptxGenJS API to add charts and tables to placeholder areas
- Use
```
pptx.writeFile()
```
  to save the presentation
Visual Validation: Generate thumbnails and check for layout issues
- Create thumbnail grid:
```
python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4
```
- Read and carefully inspect the thumbnail images:
  - Text Truncation: Text is cut off by title bars, shapes, or slide edges
  - Text Overlap: Text overlaps with other text or shapes
  - Positioning Issues: Content is too close to slide boundaries or other elements
  - Contrast Issues: Insufficient contrast between text and background
- If issues are found, adjust HTML margins/spacing/colors and regenerate the presentation
- Repeat until all slides are visually correct

Editing Existing PowerPoint Presentations

When editing slides in an existing PowerPoint presentation, you need to use the raw Office Open XML (OOXML) format. This involves unpacking the .pptx file, editing the XML content, then repacking it.

Workflow

Mandatory - Read the entire file completely: Read
```
ooxml.md
```
(approximately 500 lines) from start to finish. Do not set any scope limits when reading this file. Before editing any presentation, read the complete file content to get detailed guidance on OOXML structure and editing workflows.

Unpack the presentation:

python ooxml/scripts/unpack.py <office_file> <output_dir>

Edit XML files (mainly
```
ppt/slides/slide{N}.xml
```
and related files)
Key: Validate immediately after each edit and fix any validation errors before proceeding:
```
python ooxml/scripts/validate.py <dir> --original <file>
```

Pack the final presentation:

python ooxml/scripts/pack.py <input_directory> <office_file>

Creating New PowerPoint Presentations Using Templates

When you need to create a presentation that follows an existing template design, you need to copy and rearrange template slides, then replace placeholder content.

Workflow

Extract template text and create visual thumbnail grid:
- Extract text:
```
python -m markitdown template.pptx > template-content.md
```
- Read
```
template-content.md
```
  : Read the entire file to understand the content of the template presentation. Do not set any scope limits when reading this file.
- Create thumbnail grid:
```
python scripts/thumbnail.py template.pptx
```
- For more details, see the Creating Thumbnail Grids section
Analyze the template and save inventory to file:
- Visual Analysis: View the thumbnail grid to understand slide layouts, design patterns, and visual structure
- Create and save a template inventory file to
```
template-inventory.md
```
  , containing:
  markdown
```
# Template Inventory Analysis
**Total Slides: [count]**
**Important: Slides are indexed from 0 (first slide = 0, last slide = count-1)**

## [Category Name]
- Slide 0: [Layout code (if any)] - Description/Purpose
- Slide 1: [Layout code] - Description/Purpose
- Slide 2: [Layout code] - Description/Purpose
[... List each slide individually with its index ...]
```
- Use the Thumbnail Grid: Reference the visual thumbnails to identify:
  - Layout patterns (title slides, content layouts, section dividers)
  - Image placeholder positions and quantities
  - Design consistency between slide groups
  - Visual hierarchy and structure
- This inventory file is required for selecting appropriate templates in the next step
Create presentation outline based on template inventory:
- Review the available templates from step 2.
- Select an introduction or title template for the first slide. This should be one of the frontmost templates.
- Select safe, text-based layouts for other slides.
- Key: Match layout structure to actual content:
  - Single-column layout: For unified narratives or single topics
  - Two-column layout: Only use when you have exactly 2 distinct items/concepts
  - Three-column layout: Only use when you have exactly 3 distinct items/concepts
  - Image+text layout: Only use when you have actual images to insert
  - Quote layout: Only use for actual person quotes (with attribution), never for emphasis
  - Never use layouts with more placeholders than content
  - If you have 2 items, don't force them into a 3-column layout
  - If you have 4+ items, consider splitting into multiple slides or using list format
- Calculate your actual content quantity before selecting layouts
- Verify that each placeholder in the selected layout will be filled with meaningful content
- Select an option that represents the best layout for each content section.
- Save
```
outline.md
```
  , containing content and template mapping that utilizes available designs
- Example template mapping:
```
# Template Slides to Use (0-based index)
# Warning: Verify indexes are within range! A template with 73 slides has indexes 0-72
# Mapping: Slide number in outline -> Template slide index
template_mapping = [
    0,   # Use slide 0 (Title/Cover)
    34,  # Use slide 34 (B1: Title and Body)
    34,  # Use slide 34 again (copy for second B1)
    50,  # Use slide 50 (E1: Quote)
    54,  # Use slide 54 (F2: Closing + Text)
]
```
Copy, 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
```
python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52
```
- The script automatically handles copying of duplicate slides, deletion of unused slides, and reordering
- Slide indexes start at 0 (first slide is 0, second is 1, etc.)
- The same slide index can appear multiple times to copy that slide

Extract all text using the
inventory.py
script:

Run Inventory Extraction:

bash

python scripts/inventory.py working.pptx text-inventory.json

Read text-inventory.json: Read the entire text-inventory.json file to understand all shapes and their properties. Do not set any scope limits when reading this file.

Inventory JSON Structure:

json

  {
    "slide-0": {
      "shape-0": {
        "placeholder_type": "TITLE",  // or null for non-placeholders
        "left": 1.5,                  // Position (inches)
        "top": 2.0,
        "width": 7.5,
        "height": 1.2,
        "paragraphs": [
          {
            "text": "Paragraph text",
            // Optional properties (only included if non-default):
            "bullet": true,           // Explicit bullet detected
            "level": 0,               // Only included if bullet is true
            "alignment": "CENTER",    // CENTER, RIGHT (non-LEFT)
            "space_before": 10.0,     // Space before paragraph (points)
            "space_after": 6.0,       // Space after paragraph (points)
            "line_spacing": 22.4,     // Line spacing (points)
            "font_name": "Arial",     // From first run
            "font_size": 14.0,        // Points
            "bold": true,
            "italic": false,
            "underline": false,
            "color": "FF0000"         // RGB color
          }
        ]
      }
    }
  }

Key Features:
- Slides: Named "slide-0", "slide-1", etc.
- Shapes: Ordered by visual position (top to bottom, left to right) as "shape-0", "shape-1", etc.
- Placeholder Types: TITLE, CENTER_TITLE, SUBTITLE, BODY, OBJECT, or null
- Default Font Size:
```
default_font_size
```
  extracted from layout placeholders (points, if available)
- Slide Numbers Filtered: Shapes with SLIDE_NUMBER placeholder type are automatically excluded from inventory
- Bullets: When
```
bullet: true
```
  ,
```
level
```
  is always included (even if 0)
- Spacing:
```
space_before
```
  ,
```
space_after
```
  , and
```
line_spacing
```
  (points, only included if set)
- Colors:
```
color
```
  for RGB (e.g., "FF0000"),
```
theme_color
```
  for theme colors (e.g., "DARK_1")
- Properties: Only non-default values are included in output

Generate replacement text and save data to JSON file Based on the text inventory from the previous step:
- Key: First verify which shapes exist in the inventory - only reference actual existing shapes
- Validation: The replace.py script will validate that all shapes in the replacement JSON exist in the inventory
  - If you reference a non-existent shape, you will receive an error showing available shapes
  - If you reference a non-existent slide, you will receive an error indicating the slide does not exist
  - All validation errors are shown at once before the script exits
- Important: The replace.py script internally uses inventory.py to identify all text shapes
- Automatic Clearing: All text shapes in the inventory will be cleared unless you provide "paragraphs" for them
- Add the "paragraphs" field (not "replacement_paragraphs") for shapes that need content
- Shapes without "paragraphs" in the replacement JSON will be automatically cleared of text
- Bulleted paragraphs will be automatically left-aligned. Do not set the
```
alignment
```
  property when
```
"bullet": true
```
- Generate appropriate replacement content for placeholder text
- Use shape size to determine appropriate content length
- Key: Include paragraph properties from the original inventory - don't just provide text
- Important: When bullet: true, do not include bullet symbols (•, -, *) in the text - they will be added automatically
- Basic Formatting Rules:
  - Titles should typically have
    "bold": true
  - List items should have
    "bullet": true, "level": 0
    (level is required when bullet is true)
  - Preserve any alignment properties (e.g.,
    "alignment": "CENTER"
    for centered text)
  - Include font properties when different from defaults (e.g.,
    "font_size": 14.0
    ,
    "font_name": "Lora"
    )
  - Colors: Use
    "color": "FF0000"
    for RGB,
    "theme_color": "DARK_1"
    for theme colors
  - The replacement script expects properly formatted paragraphs, not just text strings
  - Overlapping Shapes: Prioritize shapes with larger default_font_size or more appropriate placeholder_type
- Save the updated inventory with replacements to
```
replacement-text.json
```
- Warning: Different template layouts have different numbers of shapes - always check the actual inventory before creating replacements
Example properly formatted paragraphs field:
json
```
"paragraphs": [
  {
    "text": "New presentation title text",
    "alignment": "CENTER",
    "bold": true
  },
  {
    "text": "Section title",
    "bold": true
  },
  {
    "text": "First bullet point, no bullet symbol",
    "bullet": true,
    "level": 0
  },
  {
    "text": "Red text",
    "color": "FF0000"
  },
  {
    "text": "Theme color text",
    "theme_color": "DARK_1"
  },
  {
    "text": "Normal paragraph text without special formatting"
  }
]
```
Shapes not listed in replacement JSON will be automatically cleared:
json
```
{
  "slide-0": {
    "shape-0": {
      "paragraphs": [...] // This shape gets new text
    }
    // shape-1 and shape-2 from inventory will be automatically cleared
  }
}
```
Common Formatting Patterns for Presentations:
- Title slides: bold text, sometimes centered
- Section titles within slides: bold text
- Bullet lists: each item needs
```
"bullet": true, "level": 0
```
- Body text: usually no special properties needed
- Quotes: may have special alignment or font properties
Apply replacements using the
replace.py
script
bash
```
python scripts/replace.py working.pptx replacement-text.json output.pptx
```
The script will:
- First extract an inventory of all text shapes using functions from inventory.py
- Validate that all shapes in the replacement JSON exist in the inventory
- Clear text from all shapes identified in the inventory
- Apply new text only to shapes where "paragraphs" are defined in the replacement JSON
- Preserve formatting by applying paragraph properties from the JSON
- Automatically handle bullets, alignment, font properties, and colors
- Save the updated presentation
Example validation errors:
```
Error: Invalid shapes in replacement JSON:
  - Shape 'shape-99' not found on 'slide-0'. Available shapes: shape-0, shape-1, shape-4
  - Slide 'slide-999' not found in inventory
```
```
Error: Replacement text worsens overflow for the following shapes:
  - slide-0/shape-2: overflow increased by 1.25" (was 0.00", now 1.25")
```

Creating Thumbnail Grids

To create a visual thumbnail grid of PowerPoint slides for quick analysis and reference:

bash

python scripts/thumbnail.py template.pptx [output_prefix]

Features:

Creates:

thumbnails.jpg

(or

thumbnails-1.jpg

thumbnails-2.jpg

, etc. for large presentations)

Default: 5 columns, max 30 slides per grid (5×6)
Custom prefix:
```
python scripts/thumbnail.py template.pptx my-grid
```
- Note: If you want to output to a specific directory, the output prefix should include the path (e.g.,
```
workspace/my-grid
```
  )
Adjust column count:
```
--cols 4
```
(range: 3-6, affects number of slides per grid)
Grid limits: 3 columns = 12 slides/grid, 4 columns = 20, 5 columns = 30, 6 columns = 42
Slides are zero-indexed (slide 0, slide 1, etc.)

Use Cases:

Template analysis: Quickly understand slide layouts and design patterns
Content review: Visual overview of the entire presentation
Navigation reference: Find specific slides by appearance
Quality check: Verify all slides are formatted correctly

Examples:

bash

# Basic usage
python scripts/thumbnail.py presentation.pptx

# Combined options: custom name, column count
python scripts/thumbnail.py template.pptx analysis --cols 4

Converting Slides to Images

To visually analyze PowerPoint slides, use a two-step process to convert them to images:

Convert PPTX to PDF:

bash

soffice --headless --convert-to pdf template.pptx

Convert PDF pages to JPEG images:
bash
```
pdftoppm -jpeg -r 150 template.pdf slide
```
This creates files like
```
slide-1.jpg
```
,
```
slide-2.jpg
```
, etc.

Options:

```
-r 150
```
: Set resolution to 150 DPI (adjust to balance quality/size)
```
-jpeg
```
: Output in JPEG format (use
```
-png
```
for PNG output if needed)
```
-f N
```
: First page to convert (e.g.,
```
-f 2
```
starts from page 2)
```
-l N
```
: Last page to convert (e.g.,
```
-l 5
```
stops at page 5)
```
slide
```
: Prefix for output files

Example for specific range:

bash

pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # Convert only pages 2-5

Code Style Guide

Important: When generating code for PPTX operations:

Write concise code
Avoid verbose variable names and redundant operations
Avoid unnecessary print statements

Dependencies

Required dependencies (should already be installed):

markitdown:
```
pip install "markitdown[pptx]"
```
(for extracting text from presentations)
pptxgenjs:
```
npm install -g pptxgenjs
```
(for creating presentations via html2pptx)
playwright:
```
npm install -g playwright
```
(for HTML rendering in html2pptx)

react-icons:

npm install -g react-icons react react-dom

(for icons)

sharp:
```
npm install -g sharp
```
(for SVG rasterization and image processing)
LibreOffice:
```
sudo apt-get install libreoffice
```
(for PDF conversion)
Poppler:
```
sudo apt-get install poppler-utils
```
(for pdftoppm to convert PDF to images)
defusedxml:
```
pip install defusedxml
```
(for safe XML parsing)

pptx

NPX Install

Tags

SKILL.md Content (Chinese)

PPTX Creation, Editing, and Analysis

Overview

Reading and Analyzing Content

Text Extraction

Raw XML Access

Unpacking Files

Key File Structure

Typography and Color Extraction

Creating New PowerPoint Presentations Without Templates

Design Principles

Color Palette Selection

Visual Detail Options

Layout Tips

Workflow

Editing Existing PowerPoint Presentations

Workflow

Creating New PowerPoint Presentations Using Templates

Workflow

Creating Thumbnail Grids

Converting Slides to Images

Code Style Guide

Dependencies