document-pptx

Document PPTX

Use this skill to create, edit, inspect, troubleshoot, or automate PowerPoint presentations programmatically.

Keep the skill focused on tool choice, template safety, notes and chart workflows, and repairability. Use the helper scripts and references instead of carrying long inline library manuals in SKILL.md.

Quick Reference

Decision Rules

• start from the audience and the decision the deck must support
• use one takeaway per slide
• prefer a branded template when brand fidelity matters
• resolve template layouts by name, not guessed index
• keep chart data traceable to one source of truth
• accessibility is part of authoring, not a final afterthought
• if animations, broken content, or unreadable-content repair are in scope, treat that as specialist troubleshooting work

Template-First vs From-Scratch Judgment

Deciding whether to open a branded .pptx template or build from a blank Presentation() is the single highest-leverage call in this skill — get it wrong and every downstream slide inherits the mistake.

• Use the branded template when: the deck goes to an external audience, brand/legal review is in the approval path, the org already has a maintained .pptx/.potx, or the request mentions "our deck," "our template," or a company name.
• Build from scratch when: it's an internal working draft, no template exists yet, the ask is exploratory ("mock up a few options"), or the content is data/report-shaped and speed matters more than pixel-perfect branding.
• Red flag: never guess at brand colors, fonts, or layout names when a template is available — inventory it first (scripts/pptx_inventory.py). A plausible-looking hex code that isn't the actual brand color is worse than asking.
• Escalate to PPTX-Automizer only when a designer already owns the .pptx/.potx and the job is narrow, named-element replacement (chart data, a metric, a photo) — not general content authoring. Automizer is not a general slide-generation library; it merges into an existing structure.
• If the user has no template and no strong brand requirement, do not manufacture one — a clean, legible, unbranded deck beats an invented "corporate" look with unverified colors.

Workflow

1. Classify the job:
   • fresh deck
   • template-fill workflow
   • notes extraction
   • troubleshooting or repair
2. Choose the tool stack.
3. Build the slide narrative before writing slide code.
4. Inspect templates before automation changes.
5. Generate or edit the deck.
6. Validate notes, data, accessibility, and repairability.

ASCII Flow

PPTX request
  |
  v
Classify job
  |-- fresh editable deck ------> build narrative + choose library
  |-- branded template fill ----> inspect masters/layouts/placeholders first
  |-- notes extraction ---------> scripts/pptx_extract_notes.py
  |-- troubleshoot / repair ----> scripts/pptx_ooxml_inspect.py
  |
  v
Choose stack
  |-- Python reporting ---------> python-pptx
  |-- JS/TS export -------------> PptxGenJS
  |-- named template elements --> PPTX-Automizer
  |
  v
Generate or edit slides
  |
  v
Validate
  |-- one takeaway per slide
  |-- chart data source + units + timeframe
  |-- speaker notes
  |-- accessibility and PowerPoint repair check

Tool Selection

Known Limits

• python-pptx has no animation API (no build/entrance effects) and no slide-transition API; both require direct OOXML <p:timing>/<p:transition> manipulation — see references/pptx-animations-transitions.md before promising motion.
• python-pptx cannot create a true combo chart (e.g., column + line) from scratch — it has no multi-plot chart constructor. Style a single-type chart, or use PptxGenJS/manual PowerPoint editing when a real combo is required.
• python-pptx has no native gradient-fill API and no supported way to edit theme colors (theme1.xml) through its object model — both require direct XML manipulation with a pre-edit backup.
• The color class is RGBColor (from pptx.dml.color), not RgbColor — a one-letter-case mistake here silently raises ImportError at runtime.
• template layout indices are not portable across branded decks — resolve layouts by name every time, including on templates you have used before (designers reorder or rename layouts between versions).
• template edits can break timing, media, or repairability if done blindly
• generated decks still need an actual PowerPoint review when fidelity or accessibility matters — Keynote/Google Slides opening cleanly does not confirm PowerPoint compatibility, and the reverse is also true.

What Good Looks Like

• each slide supports one real decision or message
• branded decks respect masters, layouts, fonts, and colors
• charts carry units, timeframe, and source
• speaker notes capture exact figures and transitions
• titles, reading order, contrast, and alt text are present
• if the deck breaks, the structure is inspectable with the included scripts

Navigation

References

• references/pptx-layouts.md
• references/pptx-charts.md
• references/pptx-template-branding.md
• references/pptx-speaker-notes-delivery.md
• references/pptx-accessibility-compliance.md
• references/pptx-troubleshooting-repair.md
• references/pptx-animations-transitions.md
• data/sources.json

Scripts

• scripts/pptx_inventory.py
• scripts/pptx_extract_notes.py
• scripts/pptx_ooxml_inspect.py

Templates

• assets/pitch-deck.md
• assets/quarterly-review.md
• assets/slide-narrative-template.md

Related Skills

• ../document-pdf/SKILL.md
• ../document-xlsx/SKILL.md
• ../product-management/SKILL.md

Fact-Checking

• Verify current library behavior, packaged versions, and standards-sensitive claims before final advice.
• Prefer primary library docs and packaged release notes over summaries.
• If live verification is unavailable, mark version-sensitive guidance as unverified.

Learnings Loop

Before applying this skill on a non-trivial task, read learnings.consolidated.md in this directory (and learnings.md if present).

After applying it, if you encountered a pattern worth remembering, a mistake worth preventing, or a domain fact that surprised you, append one dated bullet to learnings.md via agents-skills-feedback-loop/scripts/append_learning.py. Do not modify SKILL.md itself.