pptx

Work with PowerPoint .pptx decks. The pptx file format is OOXML — a zip container holding XML descriptions of slides, layouts, masters, and media.

Delivery rule

First, use the available tool list for this session to choose the delivery path.

If write_file, edit_file, apply_patch, or execute_code is available:

• Build the .pptx in the active workspace using the paths below.
• Call publish_artifact for the final .pptx before your final reply when that tool is available.
• The code examples later in this document apply.

If only create_pptx is available:

• Use it only for a basic text-only deck from slide titles, body text, and bullets.
• Do not use it for illustrated, image-heavy, chart-heavy, template-based, or visually designed decks. It does not support images, icons, charts, custom layouts, or visual QA.
• If the user asked for those visual features, explain that full visual deck authoring is unavailable in this session instead of calling create_pptx as though it satisfies the request.

If none of those file-authoring tools are available:

• Do not attempt to generate, save, or modify the .pptx.
• Do not paste OOXML, Python, JavaScript, HTML, or other source as a substitute for sending the deck.
• Ignore the Path B, Path C, and Visual QA sections below; they do not apply when file authoring is unavailable.
• Reply plainly: explain that the current session cannot create files, and offer to publish an existing .pptx by path, describe the slide contents in text, or continue in a file-authoring surface such as the OpenSquilla Web UI.

In all cases, do not paste full file source as the deliverable. Source code is appropriate only when the user explicitly asks for code.

Decide the path first

Pick one of three paths up front; do not mix them. The right path depends only on what is on disk before you start.

If the user hands you a deck and asks for changes, default to path B and treat the input deck as the visual style baseline. Only fall back to path C when the user explicitly says "start fresh" or there is no input deck.

Path A: Read text from a .pptx

Use the helper script. It walks slides via the python-pptx public API and prints text grouped by slide. This is always available because python-pptx is the only hard dependency.

python {baseDir}/scripts/extract_text.py /path/to/deck.pptx
python {baseDir}/scripts/extract_text.py /path/to/deck.pptx --json

For programmatic use, call python-pptx directly:

from pptx import Presentation
prs = Presentation("deck.pptx")
for i, slide in enumerate(prs.slides, 1):
    for shape in slide.shapes:
        if shape.has_text_frame:
            for para in shape.text_frame.paragraphs:
                print(i, "".join(run.text for run in para.runs))

If markitdown is available, it gives a faster Markdown rendering:

python -m markitdown deck.pptx

Path B: Edit an existing deck

Two sub-strategies; pick by how invasive the edit is.

B1. Text-only edits (preferred)

When the change is "swap this string for that one" or "fill these placeholders": use python-pptx to mutate runs in place. This preserves all theme/master/font settings.

from pptx import Presentation
prs = Presentation("input.pptx")
slide = prs.slides[0]
for shape in slide.shapes:
    if not shape.has_text_frame:
        continue
    for para in shape.text_frame.paragraphs:
        for run in para.runs:
            if run.text == "{{TITLE}}":
                run.text = "Q3 Review"
prs.save("output.pptx")

Edit at the run level, not the paragraph level — replacing whole paragraph text drops formatting. If a placeholder spans multiple runs (often happens when the original template had partial bold/italic), concatenate the runs into the first run and clear the others.

B2. Structural edits (add/remove/reorder slides, change layouts)

python-pptx's slide-level mutation is limited (no public reorder API). For structural work, unzip the .pptx, patch ppt/presentation.xml and the slide files, and repack:

mkdir _unpacked && (cd _unpacked && unzip -q ../input.pptx)
# edit _unpacked/ppt/presentation.xml (sldIdLst order)
# edit _unpacked/ppt/slides/slideN.xml content
(cd _unpacked && zip -q -r ../output.pptx . -x "*.DS_Store")

Rules when patching slide XML:

• Use defusedxml.minidom or lxml, not stdlib xml.etree.ElementTree. ET drops or rewrites namespace prefixes (a:, p:, r:) in ways PowerPoint refuses to load.
• After deleting slides, remove their <p:sldId> from ppt/presentation.xml's <p:sldIdLst> AND remove the matching relationship in ppt/_rels/presentation.xml.rels. Skipping either yields a "repair" prompt in PowerPoint.
• Update [Content_Types].xml if you change the slide count.
• If the deck has speaker notes, each slideN.xml has a paired notesSlideN.xml referenced by slideN.xml.rels. Delete or move both together.

When done, validate by opening the output in LibreOffice headless (next section) before declaring success. An invalid deck silently fails to render in some places but loads fine in others.

Path C: Create from scratch

Use python-pptx when the runtime is Python-first (more readable, simpler deps). Use PptxGenJS when you need richer layout primitives (charts, tables with merged cells, gradients) or are already in a Node toolchain.

C1. python-pptx quick recipe

from pptx import Presentation
from pptx.util import Inches, Pt
from pptx.dml.color import RGBColor

prs = Presentation()
prs.slide_width, prs.slide_height = Inches(13.333), Inches(7.5)  # 16:9 wide

title_layout = prs.slide_layouts[0]
slide = prs.slides.add_slide(title_layout)
slide.shapes.title.text = "Q3 Review"
slide.placeholders[1].text = "Wei E."

content_layout = prs.slide_layouts[1]
slide = prs.slides.add_slide(content_layout)
slide.shapes.title.text = "Highlights"
tf = slide.placeholders[1].text_frame
tf.text = "Revenue +18% YoY"
for line in ("Churn down to 4.1%", "Two new enterprise logos"):
    p = tf.add_paragraph()
    p.text = line

prs.save("out.pptx")

See references/python_pptx.md for shapes, tables, images, charts, and color/font helpers.

C2. PptxGenJS quick recipe

const pptxgen = require("pptxgenjs");
const pres = new pptxgen();
pres.layout = "LAYOUT_WIDE"; // 13.3" × 7.5"

const slide = pres.addSlide();
slide.background = { color: "0F172A" };
slide.addText("Q3 Review", {
  x: 0.5, y: 0.6, w: 9, h: 1.2,
  fontSize: 44, bold: true, color: "FFFFFF", margin: 0,
});

await pres.writeFile({ fileName: "out.pptx" });

See references/pptxgenjs.md for the full surface.

Design checklist (apply to both C1 and C2)

Plain bullets on white look generated. Apply each item before declaring done:

• Pick a content-specific palette (one dominant color ~60% of weight, one support, one accent). Avoid generic blue.
• Title slides and section dividers in dark; content slides in light.
• Every slide carries one visual element: an icon, a stat callout, a chart, or an image. No slide is title + bullets only.
• Use varied layouts across slides — two-column, half-bleed image, stat grid, quote slide. Repeating one layout for ten pages is the strongest "AI-generated" tell.
• Header font ≥ 36 pt; body 14–16 pt. Keep ≥ 0.5" margin from slide edges.
• Left-align body paragraphs; center only titles.
• Do not add a thin colored line under every title — it is a strong visual marker for AI-generated decks.

Visual QA (required for paths B and C)

A first render is rarely correct. Render to images and inspect.

bash {baseDir}/scripts/render_thumbs.sh out.pptx
# emits out-01.jpg, out-02.jpg, ... in cwd, plus out.pdf

The script needs soffice (LibreOffice) and pdftoppm (poppler) on PATH. If either is missing, the script tells you what to install for the host OS.

Inspection prompt for a fresh-eyes pass (use a sub-agent or re-read with a different model than the one that generated the deck):

Inspect each slide image. Assume there are issues; find them.
For each slide list:
  - Overlapping text/shapes
  - Text overflow or cut off at margins
  - Decorative lines positioned for one-line titles when title wrapped to two
  - Low-contrast text (light on light or dark on dark)
  - Inconsistent spacing across analogous slides
  - Leftover placeholder text ("Lorem", "TODO", "{{...}}", "xxxx")
  - Misaligned columns or icons
Report all findings. Do not declare clean unless one fix-and-reverify cycle
has passed.

Common pitfalls

Troubleshooting

• "python-pptx not installed": run uv pip install python-pptx (or pip install python-pptx). The skill declares this under metadata.platform.install, so the eligibility report surfaces an install hint automatically when the binary is present but the module is missing.
• "command not found: soffice": on macOS brew install libreoffice; on Debian/Ubuntu sudo apt-get install -y libreoffice; on Windows install LibreOffice from libreoffice.org and add program/ to PATH. Visual QA is optional — paths A and B1 work without it.
• "command not found: pdftoppm": macOS brew install poppler; Debian/Ubuntu sudo apt-get install -y poppler-utils; Windows ships it inside the LibreOffice install or via pdftoppm from poppler-windows releases.
• PptxGenJS path fails with MODULE_NOT_FOUND: npm install -g pptxgenjs or run inside a Node project where it is a local dependency.

Boundaries

• This skill is for .pptx (Office Open XML PresentationML). It is not for .ppt (legacy binary), Google Slides, or Keynote files. Convert those to .pptx first (LibreOffice or Keynote export).
• Do not embed external macro logic (.pptm / VBA). Bundled Codex sandboxes do not execute the embedded code, and security scanners flag mixed content.
• Source and runtime dependency notices are recorded in THIRD_PARTY_NOTICES.md.