pptx skill

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 LAYOUT16x9 = 10" × 5.625", not 13.3" wide. Coordinates past the edge are written, not clamped — the shape just isn't on the slide. (LAYOUTWIDE 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 ROUNDEDRECTANGLE**, not RECTANGLE.
• Gradient fills aren't supported — use a gradient image as the background instead.
• Every addText call without a placeholder needs isTextBox: true — without it the shape lacks txBox="1", so screen readers announce the text as a "graphic" instead of a text box. No visual change.
• 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.

Structured decks

A deck built on a theme, layouts, placeholders and sections can be restyled in one place and edited in PowerPoint without fighting it. Build every new deck this way unless the user asks for a quick throwaway.

1. Theme first: const THEME = { name, headFontFace, bodyFontFace, colors: { dk1, lt1, dk2, lt2, accent1 … accent6, hlink, folHlink } }, colors in hex. pres.theme takes the two fonts and nothing else. Name no font after that — titles get the heading font, other text the body font — except on chart text, which is hard-coded Arial: give its *FontFace options "+mn-lt" (theme body font; "+mj-lt" is the heading font).
2. const C = pres.SchemeColor for every color — C.text1/C.text2 are dk1/dk2, C.background1/C.background2 are lt1/lt2. These take hex only, read from THEME: valGridLine.color, catGridLine.color, shadow.color, and on a one-series bar chart invertedColors or more than one chartColors. A scheme color there is written as without complaint, and being hex, these will not follow a later change of theme.
3. Sections: pres.addSection({ title }) just before that section's first slide, then sectionTitle on every addSlide. A slide without one — or, when sections are all declared up front, a table's auto-paged continuation slides — lands in a stray "Default-N" section.
4. One layout per slide frame (defineSlideMaster()): title, section divider, title only, chart + commentary, table; dark and light variants if the design alternates. Text regions are named placeholders carrying position, size, weight and color — chart, image and table placeholders need a color too, or prompt text and arrays of runs come out hard-coded 000000. Footer text, logo and slideNumber go on the layout, never on a slide.
5. Fill by name: addSlide({ masterName, sectionTitle }), then addText("…", { placeholder: "title" }) with no position, size or color — the placeholder's own options win, and anything it doesn't set (italic, align, fontFace) still applies; style one run with [{ text, options }]. A misspelt placeholder or masterName fails silently (a stray text box at 0,0; the blank layout). Only title, body and chart placeholders fill by name alone: addImage({ placeholder }) takes the placeholder's x and y but not its size (a 1" × 1" picture) — pass w/h too. addTable({ placeholder }) takes its x and y only — always pass w; when it auto-pages it ignores the placeholder and runs off the slide, so also pass x, y and autoPageSlideStartY (same as y, or continuation pages are laid out from the top margin), give the layout a margin whose bottom clears the footer, and fill the continuation slides' titles through slide.newAutoPagedSlides.
6. A layout is the frame, not the "layout" Design Ideas means. Cards, icons, stat callouts and images are still composed slide by slide on top of it, in scheme colors, each with an objectName — every Design Idea applies, and most content slides sit on the title-only layout.
7. Write, then apply the theme: await pres.writeFile({ fileName: "deck.pptx" }), then await applyTheme("deck.pptx", THEME). pptxgenjs cannot write theme colors: until this runs, scheme colors resolve to Office's stock palette. It throws, changing nothing, on a scheme color in a hex-only option — fix what it names and rebuild.

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 slide_text.py 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 -XrD ../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 , including one you just wrote.
• Never copy a slide file by hand — addslide.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: addslide.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 addslide(layout)), preserve formatting through textframe.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 per list item — never concatenate items into a single paragraph. Copy the sibling to preserve spacing, and put b="1" on the of titles, section headers, and inline labels (Status:, Owner:).
• Let bullets inherit from the layout; only add , (numbered), or to override — never a literal • in the text.
• Text with leading or trailing spaces needs xml:space="preserve" on its .

Deck content and flow

• One message per slide. A deck goes theme by theme, message by message.
• A common structure is the pyramid: the main message up front, an executive summary that previews the sections, the sections themselves, then a conclusion, usually with next steps that act on the findings.
• Match the structure to the size of the deck. A short deck might not need an introduction and a conclusion; a long deck might need dividers between topics.
• Build toward what the deck is for: a decision, consensus, a celebration, resolving a disagreement, or opening a discussion.
• Build for how it will be used. A live deck gets narration and possibly discussion; a pre-read has to carry the whole narrative itself. An executive audience in a live meeting needs few words and highly visual slides. Detailed, word-heavy slides are sometimes right for subject-matter experts or for a deck read offline. Analytical reports lean on charts and tables.
• Size a live deck to the talk: about 1.5 to 2 minutes per slide, with time left for questions if there will be any.

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

Data display:

• Large stat callouts (big numbers 60-72pt with small labels below)
• Comparison columns (before/after, pros/cons, side-by-side options)
• Timeline or process flow (numbered steps, arrows)

Visual polish:

• Icons in small colored circles next to section headers
• Italic accent text for key stats or taglines

Typography

Font names you write into the .pptx are rendered by the user's PowerPoint, not by this environment. Your visual QA renders via LibreOffice, which substitutes fonts it doesn't have — and for some fonts the substitute has different widths, so your QA preview can show text overflow (or fit) that the real deck won't have. To keep your QA trustworthy:

• Safe fonts (render true-to-width in QA and ship with Office): Arial, Calibri, Cambria, Times New Roman, Courier New, Bookman Old Style, Century Schoolbook. Use these for body text and anything where fit matters.
• Headers with personality at zero QA risk: pair a safe-list serif header (Cambria, Bookman Old Style, Century Schoolbook) with a safe-list sans body (Calibri or Arial). You get visual contrast without giving up reliable overflow checks.
• If the user asks for a font outside the safe list (e.g. Georgia or Trebuchet MS): use it where the user asked, but size those containers with extra slack (~10%) and don't trust QA text-fit on those elements — the preview of that font is approximate. If the user hasn't specified, prefer safe-list fonts for body text.
• QA-unreliable fonts (substitute has different widths — overflow checks can be wrong): Georgia, Trebuchet MS, Impact, Arial Black, Garamond, Consolas, Palatino Linotype. Calibri Light substitution varies by environment; treat as QA-unreliable. Fine for titles/accents with slack; don't trust QA text-fit on these.
• Never default to Aptos — Office's post-2023 default has no metric-compatible substitute here and is missing from older Office installs, so it's unreliable on both ends.

Spacing

• 0.5" mi