---

name: pptx description: Read, create, edit, and review PPTX files; convert HTML to PPTX; and perform OOXML workflows. Use when users mention PowerPoint, slides, pptx editing, or slide automation.

PowerPoint Reading, Creation, and Editing

Overview

Use python-pptx for most PPTX operations. For advanced features (template-based creation, HTML conversion, OOXML manipulation), see the Advanced Workflows section.

Reading PPTXs

If _parsed/ folder exists (preferred)

Use rg to search parsed markdown, then cat to read specific pages:

Copyrg "search term" /root/workspace/Presentation_parsed/
cat /root/workspace/Presentation_parsed/page_3.md

If no _parsed/ folder

Option 1: Text extraction with markitdown

Copypython -m markitdown file.pptx

Option 2: Text extraction with python-pptx

Copyfrom pptx import Presentation
prs = Presentation('file.pptx')
for slide in prs.slides:
    for shape in slide.shapes:
        if hasattr(shape, 'text'):
            print(shape.text)

Option 3: Visual inspection (when layout matters)

Copysoffice --headless --convert-to pdf file.pptx
pdftoppm -png file.pdf /root/tmp/slide

Then view the PNG files to inspect formatting.

Creating PPTXs

Use python-pptx to create new presentations:

Copyfrom pptx import Presentation
from pptx.util import Inches, Pt
from pptx.enum.text import PP_ALIGN

prs = Presentation()

# Title slide
title_slide_layout = prs.slide_layouts[0]
slide = prs.slides.add_slide(title_slide_layout)
title = slide.shapes.title
subtitle = slide.placeholders[1]
title.text = "Presentation Title"
subtitle.text = "Subtitle text"

# Content slide with bullet points
bullet_slide_layout = prs.slide_layouts[1]
slide = prs.slides.add_slide(bullet_slide_layout)
shapes = slide.shapes
title_shape = shapes.title
body_shape = shapes.placeholders[1]

title_shape.text = "Slide Title"
tf = body_shape.text_frame
tf.text = "First bullet point"
p = tf.add_paragraph()
p.text = "Second bullet point"
p.level = 0
p = tf.add_paragraph()
p.text = "Sub-bullet"
p.level = 1

# Save
prs.save('/root/workspace/output.pptx')

After creating: Save the PPTX under /root/workspace so it syncs automatically.

Editing PPTXs

Modify existing slides

Copyfrom pptx import Presentation

prs = Presentation('/root/workspace/file.pptx')

# Access first slide
slide = prs.slides[0]

# Modify title
if slide.shapes.title:
    slide.shapes.title.text = "New Title"

# Find and modify text in shapes
for shape in slide.shapes:
    if hasattr(shape, 'text_frame'):
        for paragraph in shape.text_frame.paragraphs:
            for run in paragraph.runs:
                if 'old text' in run.text:
                    run.text = run.text.replace('old text', 'new text')

prs.save('/root/workspace/file.pptx')

Add images

Copyfrom pptx import Presentation
from pptx.util import Inches

prs = Presentation('/root/workspace/file.pptx')
slide = prs.slides[0]

left = Inches(1)
top = Inches(2)
width = Inches(4)
slide.shapes.add_picture('image.png', left, top, width=width)

prs.save('/root/workspace/file.pptx')

Add tables

Copyfrom pptx import Presentation
from pptx.util import Inches

prs = Presentation()
slide = prs.slides.add_slide(prs.slide_layouts[5])  # Blank layout

rows, cols = 3, 4
left, top = Inches(1), Inches(2)
width, height = Inches(8), Inches(2)

table = slide.shapes.add_table(rows, cols, left, top, width, height).table

table.cell(0, 0).text = "Header 1"
table.cell(0, 1).text = "Header 2"
table.cell(1, 0).text = "Data 1"
table.cell(1, 1).text = "Data 2"

prs.save('/root/workspace/output.pptx')

Visual Verification

After creating or editing presentations, render specific slides and inspect:

Copysoffice --headless --convert-to pdf /root/workspace/output.pptx
pdftoppm -png -f 1 -l 3 /root/workspace/output.pdf /root/tmp/slide  # slides 1-3
# Then call: view { path: "/root/tmp/slide-1.png" }

For thumbnail overview:

Copypython /root/skills/pptx/scripts/thumbnail.py output.pptx /root/tmp/thumbnails --cols 4
# Then call: view { path: "/root/tmp/thumbnails/grid.png" }

Keep verification targeted—inspect only the slides you edited.

Quality Expectations

• No formatting defects: text cutoff, misaligned elements, broken layouts
• No Unicode issues: Use ASCII hyphens, not special Unicode dashes
• No AI citation tokens: Never include [145036110387964†L158-L160] or 【turn...】 in presentations
• Professional styling: consistent fonts, colors, alignment across slides

---

Speaker Notes (Review Workflow)

Use /root/skills/pptx/scripts/notes.py to add, list, update, and clear speaker notes for presentation review and feedback.

Command Line

Copy# Add a note to a slide
python /root/skills/pptx/scripts/notes.py add file.pptx 1 "Remember to emphasize this point"

# List all notes
python /root/skills/pptx/scripts/notes.py list file.pptx

# Get note from specific slide
python /root/skills/pptx/scripts/notes.py get file.pptx 3

# Append to existing note
python /root/skills/pptx/scripts/notes.py append file.pptx 2 "Additional feedback here"

# Add formatted review comment (with timestamp)
python /root/skills/pptx/scripts/notes.py review file.pptx 3 "This slide needs more data" --reviewer "John"

# Clear note from slide
python /root/skills/pptx/scripts/notes.py clear file.pptx 1

# Clear all notes
python /root/skills/pptx/scripts/notes.py clear-all file.pptx

Python API

For Python API usage, see reference.md.

---

Advanced Workflows

Creating from HTML (html2pptx)

For complex layouts with precise positioning, use the html2pptx workflow:

1. MANDATORY: Read html2pptx.md completely for detailed syntax
2. Create HTML files for each slide (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
   • CRITICAL: Rasterize gradients and icons as PNG images FIRST using Sharp
3. Create and run JavaScript using /root/skills/pptx/scripts/html2pptx.js:

   Copyconst { html2pptx } = require('/root/skills/pptx/scripts/html2pptx.js');
   // Process each HTML file, add charts/tables, save with pptx.writeFile()
   

4. Visual validation: Generate thumbnails and inspect for layout issues:

   Copypython /root/skills/pptx/scripts/thumbnail.py output.pptx thumbnails --cols 4
   

   • Check for: text cutoff, overlap, positioning issues, contrast problems
   • If issues found, adjust HTML and regenerate

Template-Based Creation

When creating a presentation that follows an existing template's design:

1. Extract template text AND create visual thumbnail grid:

   Copypython -m markitdown template.pptx > template-content.md
   python /root/skills/pptx/scripts/thumbnail.py template.pptx
   

   Read template-content.md completely to understand template contents.

2. Analyze template and create inventory: Review thumbnail grid(s) to understand slide layouts. Create template-inventory.md:

   Copy# Template Inventory Analysis
   **Total Slides: [count]**
   **IMPORTANT: Slides are 0-indexed (first slide = 0)**
   
   ## [Category Name]
   - Slide 0: [Layout code] - Description/purpose
   - Slide 1: [Layout code] - Description/purpose
   

3. Create presentation outline:

   • Choose intro/title template for first slide
   • Match layout structure to content: 2-column for 2 items, 3-column for 3 items
   • Save outline.md with template mapping:

   Copytemplate_mapping = [0, 34, 34, 50, 54]  # 0-based indices
   

4. Rearrange slides using rearrange.py (edits in place):

   Copypython /root/skills/pptx/scripts/rearrange.py working.pptx 0,34,34,50,52
   

   Handles duplicating, deleting, and reordering automatically.

5. Extract ALL text using inventory.py:

   Copypython /root/skills/pptx/scripts/inventory.py working.pptx text-inventory.json
   

   Read text-inventory.json completely. Structure:

   Copy{"slide-0": {"shape-0": {"placeholder_type": "TITLE", "paragraphs": [...]}}}
   

6. Generate replacement text: Create replacement-text.json with new content. ALL text shapes are cleared unless you provide "paragraphs":

   Copy{"slide-0": {"shape-0": {"paragraphs": [{"text": "New Title", "bold": true}]}}}
   

   Include formatting: "bullet": true, "level": 0 for lists, "alignment": "CENTER" for centered text.

7. Apply replacements (edits in place):

   Copypython /root/skills/pptx/scripts/replace.py working.pptx replacement-text.json
   

OOXML Direct Editing

For comments, speaker notes, animations, complex formatting:

1. Read ooxml.md for detailed OOXML structure guidance

2. Unpack:

   Copypython /root/skills/pptx/ooxml/scripts/unpack.py file.pptx unpacked/
   

3. Key files:

   • ppt/slides/slide{N}.xml - Slide contents
   • ppt/notesSlides/notesSlide{N}.xml - Speaker notes
   • ppt/theme/theme1.xml - Colors and fonts
   • ppt/presentation.xml - Main metadata and slide references

4. Edit XML files

5. Validate immediately after each edit:

   Copypython /root/skills/pptx/ooxml/scripts/validate.py unpacked/ --original file.pptx
   

6. Pack:

   Copypython /root/skills/pptx/ooxml/scripts/pack.py unpacked/ output.pptx
   

---

Design Guidelines

Color Palette Selection

• Think beyond defaults - match colors to topic/industry/mood
• Build a 3-5 color palette (dominant + supporting + accent)
• Ensure text has strong contrast on backgrounds

Example palettes:

• Classic Blue: #1C2833, #2E4053, #AAB7B8, #F4F6F6
• Teal & Coral: #5EA8A7, #277884, #FE4447, #FFFFFF
• Black & Gold: #BF9A4A, #000000, #F4F6F6
• Bold Red: #C0392B, #E74C3C, #F39C12, #2ECC71
• Warm Blush: #A49393, #EED6D3, #E8B4B8, #FAF7F2
• Deep Purple & Emerald: #B165FB, #181B24, #40695B, #FFFFFF
• Charcoal & Red: #292929, #E33737, #CCCBCB
• Vibrant Orange: #F96D00, #F2F2F2, #222831
• Forest Green: #191A19, #4E9F3D, #1E5128, #FFFFFF

Typography

• Use web-safe fonts: Arial, Helvetica, Times New Roman, Georgia, Courier New, Verdana
• Create clear hierarchy through size, weight, color
• Ensure readability with strong contrast

Layout Tips

• Two-column layout (preferred) for slides with charts/tables
• Full-slide layout for maximum impact
• NEVER vertically stack charts below text

Dependencies

Pre-installed in sandbox:

• python-pptx - PowerPoint manipulation
• markitdown - Text extraction
• pptxgenjs - HTML to PPTX conversion
• LibreOffice - PDF conversion
• poppler-utils - PDF to image conversion