A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.
A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.
Reading and analyzing content
Text extraction
If you just need to read the text contents of a presentation, you should convert the document to markdown:
# Convert document to markdown
python -m markitdown path-to-file.pptx
Raw XML access
You need raw XML access for: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. For any of these features, you'll need to unpack a presentation and read its raw XML contents.
Note: The unpack.py script is located at skills/pptx/ooxml/scripts/unpack.py relative to the project root. If the script doesn't exist at this path, use find . -name "unpack.py" to locate it.
Key file structures
ppt/presentation.xml - Main presentation metadata and slide references
Thick single-color borders (10-20pt) on one side only
Double-line borders with contrasting colors
Corner brackets instead of full frames
L-shaped borders (top+left or bottom+right)
Underline accents beneath headers (3-5pt thick)
Typography Treatments:
Extreme size contrast (72pt headlines vs 11pt body)
All-caps headers with wide letter spacing
Numbered sections in oversized display type
Monospace (Courier New) for data/stats/technical content
Condensed fonts (Arial Narrow) for dense information
Outlined text for emphasis
Chart & Data Styling:
Monochrome charts with single accent color for key data
Horizontal bar charts instead of vertical
Dot plots instead of bar charts
Minimal gridlines or none at all
Data labels directly on elements (no legends)
Oversized numbers for key metrics
Layout Innovations:
Full-bleed images with text overlays
Sidebar column (20-30% width) for navigation/context
Modular grid systems (3×3, 4×4 blocks)
Z-pattern or F-pattern content flow
Floating text boxes over colored shapes
Magazine-style multi-column layouts
Background Treatments:
Solid color blocks occupying 40-60% of slide
Gradient fills (vertical or diagonal only)
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 (PREFERRED): Use a header spanning the full width, then two columns below - text/bullets in one column and the featured content in the other. 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 the featured content (chart/table) take up the entire slide for maximum impact and readability
NEVER vertically stack: Do not place charts/tables below text in a single column - this causes poor readability and layout issues
Workflow
MANDATORY - READ ENTIRE FILE: Read html2pptx.md completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with presentation creation.
Create an HTML file for each slide with proper dimensions (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 (render with gray background for visibility)
CRITICAL: Rasterize gradients and icons as PNG images FIRST using Sharp, then reference in HTML
LAYOUT: For slides with charts/tables/images, use either 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
Add charts and tables to placeholder areas using PptxGenJS API
Save the presentation using pptx.writeFile()
Visual validation: Generate thumbnails and inspect for layout issues
Read and carefully examine the thumbnail image 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
If issues found, adjust HTML margins/spacing/colors and regenerate the presentation
Repeat until all slides are visually correct
Editing an existing PowerPoint presentation
When edit slides in an existing PowerPoint presentation, you need to work with the raw Office Open XML (OOXML) format. This involves unpacking the .pptx file, editing the XML content, and repacking it.
Workflow
MANDATORY - READ ENTIRE FILE: Read ooxml.md (~500 lines) completely from start to finish. NEVER set any range limits when reading this file. Read the full file content for detailed guidance on OOXML structure and editing workflows before any presentation editing.
Unpack the presentation: python ooxml/scripts/unpack.py <office_file> <output_dir>
Edit the XML files (primarily ppt/slides/slide{N}.xml and related files)
CRITICAL: 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 a new PowerPoint presentation using a template
When you need to create a presentation that follows an existing template's design, you'll need to duplicate and re-arrange template slides before then replacing placeholder context.
Workflow
Extract template text AND create visual thumbnail grid:
Read template-content.md: Read the entire file to understand the contents of the template presentation. NEVER set any range limits when reading this file.
This inventory file is REQUIRED for selecting appropriate templates in the next step
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 you have exactly 2 distinct items/concepts
Three-column layouts: Use ONLY when you have exactly 3 distinct items/concepts
Image + text layouts: Use ONLY when you have 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 you have content
If you have 2 items, don't force them into a 3-column layout
If you have 4+ items, consider breaking into multiple slides or using a list format
Count your 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)
]
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:
Read text-inventory.json: Read the entire text-inventory.json file to understand all shapes and their properties. NEVER set any range limits when reading this file.
The inventory JSON structure:
{"slide-0":{"shape-0":{"placeholder_type":"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
Generate replacement text and save the data to a JSON file
Based on the text inventory from the previous step:
CRITICAL: First verify which shapes exist in the inventory - only reference shapes that are actually present
VALIDATION: The replace.py script will validate that all shapes in your replacement JSON exist in the inventory
If you reference a non-existent shape, you'll get an error showing available shapes
If you reference a non-existent slide, you'll get an error indicating the slide doesn't exist
All validation errors are shown at once before the script exits
IMPORTANT: The replace.py script uses inventory.py internally to identify ALL text shapes
AUTOMATIC CLEARING: ALL text shapes from the inventory will be cleared unless you provide "paragraphs" for them
Add a "paragraphs" field to shapes that need content (not "replacement_paragraphs")
Shapes without "paragraphs" in the replacement JSON will have their text cleared automatically
Paragraphs with bullets will be automatically left aligned. Don't set the alignment property on when "bullet": true
Generate appropriate replacement content for placeholder text
Use shape size to determine appropriate content length
CRITICAL: Include paragraph properties from the original inventory - don't just provide text
IMPORTANT: When bullet: true, do NOT include bullet symbols (•, -, *) in text - they're added automatically
ESSENTIAL FORMATTING RULES:
Headers/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 default (e.g., "font_size": 14.0, "font_name": "Lora")
Colors: Use "color": "FF0000" for RGB or "theme_color": "DARK_1" for theme colors
The replacement script expects properly formatted paragraphs, not just text strings
Overlapping shapes: Prefer shapes with larger default_font_size or more appropriate placeholder_type
First extract the 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 with "paragraphs" defined in the replacement JSON
Preserve formatting by applying paragraph properties from the JSON
Handle bullets, alignment, font properties, and colors automatically
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 made overflow worse in these shapes:
- slide-0/shape-2: overflow worsened by 1.25" (was 0.00", now 1.25")
Creating Thumbnail Grids
To create visual thumbnail grids of PowerPoint slides for quick analysis and reference:
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 in points extracted from layout placeholders (when available)
Slide numbers are 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 in points (only included when 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 the output
replacement-text.json
WARNING: Different template layouts have different shape counts - always check the actual inventory before creating replacements
Example paragraphs field showing proper formatting:
"paragraphs":[{"text":"New presentation title text","alignment":"CENTER","bold":true},{"text":"Section Header","bold":true},{"text":"First bullet point without bullet symbol","bullet":true,"level":0},{"text":"Red colored text","color":"FF0000"},{"text":"Theme colored text","theme_color":"DARK_1"},{"text":"Regular paragraph text without special formatting"}]
Shapes not listed in the replacement JSON are automatically cleared:
{"slide-0":{"shape-0":{"paragraphs":[...]// This shape gets new text}// shape-1 and shape-2 from inventory will be cleared automatically}}
Common formatting patterns for presentations:
Title slides: Bold text, sometimes centered
Section headers 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
