docvinum/agent-skills/pptx

PPTX creation, editing, and analysis

A .pptx is a ZIP archive of XML files. Choose your approach by task:

Scripts

Paths are relative to this skill's directory. Everything else is plain Python, node, or shell.

Creating with pptxgenjs — gotchas

pptxgenjs is preinstalled — do not run npm install first; write the script and require('pptxgenjs') directly. Only if that require fails: npm install pptxgenjs. The model knows the API; these are the footguns:

• Set `pres.layout` before adding slides. The default canvas is LAYOUT_16x9 = 10" × 5.625", not 13.3" wide. Coordinates past the edge are written, not clamped — the shape just isn't on the slide. (LAYOUT_WIDE is 13.3" × 7.5".)
• Hex colors: never `#`, never 8 digits. color: "FF0000". Both "#FF0000" and alpha baked into the hex ("00000020") corrupt the file. For translucency: transparency: 0-100 on fills and images, opacity: 0.0-1.0 on shadows — each is silently ignored on the other.
• pptxgenjs mutates option objects in place (converts values to EMU on first use). Never share one shadow/options object across two add* calls — build a fresh object each time.
• Shadow `offset` must be ≥ 0 — a negative offset corrupts the file. To cast a shadow upward, use angle: 270 with a positive offset.
• `letterSpacing` is silently ignored — the real option is charSpacing.
• Lists: bullet: true on each item, never a literal • (renders double bullets). Set breakLine: true on every array item except the last. Space bulleted paragraphs with paraSpaceAfter, not lineSpacing (huge gaps).
• One `new pptxgen()` per output file — never reuse an instance.
• `rectRadius` only works on `ROUNDED_RECTANGLE`, not RECTANGLE.
• Gradient fills aren't supported — use a gradient image as the background instead.
• Text boxes have built-in internal padding — set margin: 0 whenever text must align with a shape, line, or icon at the same x.
• Speaker notes go in `slide.addNotes("...")` (plain text, once per slide), never in a text box on the slide.
• Keep charts native. Use addChart() for everything PowerPoint can chart (pass an array of {type, data, options} for combos). For PowerPoint-native features the library doesn't expose (trendlines, error bars), compute the extra series yourself or post-process the generated OOXML — do not fall back to a rendered image. Only chart types PowerPoint has no native form for (Sankey, network, chord) go in as images.
• Default charts render bare — no title, no data labels, dated palette. Set showTitle + title, showValue: true + dataLabelPosition, chartColors: [...] from your palette, and quiet the frame (catAxisLabelColor/valAxisLabelColor, valGridLine: { color, size }, catGridLine: { style: "none" }, showLegend: false for a single series).
• On a stacked bar or column chart, `dataLabelPosition` must be `ctr`, `inEnd`, or `inBase`. outEnd corrupts the file.
• A combo series using `secondaryValAxis`/`secondaryCatAxis` needs both `valAxes` and `catAxes` on the chart options, two entries each. Without them pptxgenjs writes axis ids it never declares, and PowerPoint discards that chart and reports the file as corrupt. Supplying only valAxes is not enough.
• After `writeFile()`, run `python scripts/office/validate.py deck.pptx`. It reports the two chart faults above and the slide-XML defects PowerPoint refuses, and names the fix for each. Fix them in your generator, not by hand-editing the packed XML.
• Never reorder the children of `<p:presentation>`. pptxgenjs writes <p:notesMasterIdLst> right after <p:sldIdLst> and points both masters at one theme part. PowerPoint reads that happily — move the element and the same deck becomes unopenable.
• Icons: render react-icons to SVG (ReactDOMServer.renderToStaticMarkup), rasterize with sharp at ≥256px, and insert via addImage({ data: "image/png;base64," + buf.toString("base64") }) — the image/png;base64, prefix is required (react-icons, react, react-dom, and sharp are preinstalled — npm install react-icons react react-dom sharp only if a require fails).

Editing existing decks and templates

Pick layouts first: python scripts/thumbnail.py template.pptx template-thumbs writes a labeled grid of every slide and prints the file(s) it created — template-thumbs.jpg, split into template-thumbs-N.jpg past 12 slides. Always pass that second argument, named after the deck. It defaults to thumbnails, so two decks thumbnailed in one directory silently overwrite each other's grids — the first deck's are simply gone (template analysis only — visual QA needs the full-resolution renders from Converting to Images; it only accepts .pptx, so copy a .potx to a .pptx name first). Use it with markitdown to map each content section onto a template slide, and vary the layouts — don't put every section on the same title-and-bullets slide.

python3 -c "import sys,zipfile; zipfile.ZipFile(sys.argv[1]).extractall('unpacked')" deck.pptx
python scripts/add_slide.py unpacked/ slide2.xml --after slide2.xml   # duplicate a slide (or slideLayoutN.xml); prints the new slide's path
# reorder / delete slides = edit <p:sldIdLst> in ppt/presentation.xml
python scripts/clean.py unpacked/                                     # after deletions: removes orphaned slides, media, rels
# edit slide content in ppt/slides/slideN.xml
(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .)           # zip from INSIDE the dir; rm first or deleted parts survive
python scripts/office/validate.py out.pptx --original deck.pptx

• Do all structural work — add, delete, reorder — before editing any slide's content. add_slide.py copies a slide file verbatim, so duplicating after you edit clones the edited content; and clean.py deletes any slide missing from <p:sldIdLst>, including one you just wrote.
• Never copy a slide file by hand — add_slide.py does every registration a new slide needs and reports what it made (Created ppt/slides/slide17.xml from slide2.xml). It also works directly on a file: add_slide.py deck.pptx slide2.xml -o out.pptx — pass `-o`, or it rewrites the input deck in place. A duplicated slide still references its source's chart/SmartArt/embedded-object parts rather than cloning them, so editing one slide's chart changes the other's.
• If you use `python-pptx`, three things it won't do: duplicate a slide (its only entry point is add_slide(layout)), preserve formatting through text_frame.text = "..." (that collapses the paragraph to a single unstyled run — assign run.text instead), or read the SVG/EMF most template art uses (add_picture raises UnidentifiedImageError).
• Legacy .ppt must be converted first: python scripts/office/soffice.py --headless --convert-to pptx file.ppt. .potx templates unpack and pack identically — keep the .potx extension on the output.
• To reuse a template icon or image, duplicate a slide or layout that already contains it.

When filling in a template:

• If you script an XML transform, parse with defusedxml.minidom — round-tripping OOXML through xml.etree.ElementTree rewrites namespace prefixes and corrupts the deck.
• Template slots ≠ source items. If the template shows 4 team members and you have 3, delete the 4th member's entire group (image + text boxes), not just its text — then check for orphaned visuals in QA.
• One <a:p> per list item — never concatenate items into a single paragraph. Copy the sibling <a:pPr> to preserve spacing, and put b="1" on the <a:rPr> of titles, section headers, and inline labels (Status:, Owner:).
• Let bullets inherit from the layout; only add <a:buChar>, <a:buAutoNum> (numbered), or <a:buNone> to override — never a literal • in the text.
• Text with leading or trailing spaces needs xml:space="preserve" on its <a:t>.

Design Ideas

Don't create boring slides. Plain bullets on a white background won't impress anyone. Consider ideas from this list for each slide.

Before Starting

• Pick a bold, content-informed color palette: The palette should feel designed for THIS topic. If swapping your colors into a completely different presentation would still "work," you haven't made specific enough choices.
• Dominance over equality: One color should dominate (60-70% visual weight), with 1-2 supporting tones and one sharp accent. Never give all colors equal weight.
• Dark/light contrast: Dark backgrounds for title + conclusion slides, light for content ("sandwich" structure). Or commit to dark throughout for a premium feel.
• Commit to a visual motif: Pick ONE distinctive element and repeat it — rounded image frames, icons in colored circles. Carry it across every slide. Do not use a color bar or accent stripe as your motif (see Avoid list).

Color Palettes

Choose colors that match your topic — don't default to generic blue. Use these palettes as inspiration:

For Each Slide

Every slide needs a visual element — image, chart, icon, or shape. Text-only slides are forgettable.

Layout options:

• Two-column (text left, illustration on right)
• Icon + text rows (icon in colored circle, bold header, description below)
• 2x2 or 2x3 grid (image on one side, grid of content blocks on other)
• Half-bleed image (full left or right side) with content overlay