A .pptx is a ZIP archive of XML files. Choose your approach by task:
| Task | \nApproach | \n
|---|---|
| Create a new deck | \nCopy scripts/example_deck.js and change its theme and slides — see gotchas below — keeping it a structured deck unless the user asks for a quick throwaway | \n
| Edit an existing deck, or build from a template | \nunzip → edit ppt/slides/slideN.xml → zip | \n
| Read content | \nread_file(path=\"deck.pptx\") — the harness parses it natively, one ## Slide N: <title> section per slide; visual grid: python scripts/thumbnail.py deck.pptx | \n
Everything this skill uses is preinstalled in the sandbox. The sandbox runs as a non-root user without sudo, so apt-get install always fails; if a CLI tool is missing, use the Python or JavaScript route on this page instead.
Paths are relative to this skill's directory — the staged_at path skill_view returns. Everything else is plain Python, node, or shell.
| Script | \nWhat it does | \n
|---|---|
scripts/thumbnail.py deck.pptx [prefix] | \nLabeled grid of every slide, for picking template layouts. .pptx only. Pass prefix — it defaults to thumbnails, which overwrites the grids of any other deck done in the same directory | \n
scripts/add_slide.py unpacked/ slide2.xml [--after slideN.xml] | \nDuplicate a slide (or a slideLayoutN.xml) with all the package bookkeeping. Also takes a .pptx directly with -o out.pptx | \n
scripts/clean.py unpacked/ | \nDelete slides, media, and rels no longer referenced. Run after <p:sldIdLst> is final | \n
scripts/apply_theme.js | \nNode module: const { applyTheme } = require(\"<this skill's directory>/scripts/apply_theme.js\"). await applyTheme(\"deck.pptx\", THEME) after pres.writeFile() writes THEME's colors and name (escaped for XML) into the deck's theme, for structured decks. Also a CLI: node scripts/apply_theme.js deck.pptx theme.json | \n
scripts/example_deck.js [out.pptx] | \nA minimal structured deck — theme, two layouts with named placeholders, sections, text on a shape, a native column chart, notes — that passes validate.py. Copy it and change the content rather than rediscovering the API | \n
scripts/office/validate.py deck.pptx [--original src.pptx] | \nSchema, relationship, content-type, chart and slide checks; each failure names its fix. Pass --original for any template-derived deck — it baselines the schema checks against the template, so the template's own XSD errors don't read as yours | \n
scripts/office/soffice.py --headless --convert-to pdf deck.pptx | \nLibreOffice wrapper — bare soffice hangs in this sandbox | \n
pptxgenjs is preinstalled — do not run npm install first. Start from scripts/example_deck.js: copy it into the workspace and change the theme and slides; its calls are tested. These are the footguns:
pres.ChartType.area, bar, bar3d, bubble, doughnut, line, pie, radar, scatter. A column chart is ChartType.bar with barDir: \"col\": there is no ChartType.col, and it writes an empty chart frame without an error. Shapes are pres.ShapeType.rect, ellipse, line — on the instance, lower camelCase; there is no pptxgen.shapes.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\".)#, 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.shadow/options object across two add* calls — build a fresh object each time.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.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).new pptxgen() per output file — never reuse an instance.roundRect, rectRadius): use rect, square corners.addText with shape and fill, as example_deck.js does: addText(\"…\", { shape: pres.ShapeType.rect, fill: { color: C.accent1 }, margin: [14, 14, 0, 0], valign: \"middle\", … }). margin is in points, ordered [left, right, bottom, top]. A separate text box laid on top of a shape, or margin: 0, starts the text on the shape's edge.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.margin: 0 whenever text must align with a shape, line, or icon at the same x.slide.addNotes(\"...\") (plain text, once per slide), never in a text box on the slide.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. Native charts render in the PDF you check with: a chart missing from a rendered slide is missing in PowerPoint too. Run validate.py, which names the cause (usually an unknown ChartType), and fix the addChart call.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).#,##0, so 1.2, 2.4 and 4.1 label as 1, 2 and 4. Set dataLabelFormatCode (e.g. \"0.0\") whenever a value has decimals.plotArea: { fill: { color }, border: { pt, color } }. Top-level fill/border objects pass addChart() and then crash writeFile() with (colorStr || \"\").replace is not a function.background takes { color: \"2A211E\" } (or { path } / { data } for an image), not { fill: { color } } — that object crashes writeFile() with the same (colorStr || \"\").replace is not a function.dataLabelPosition must be ctr, inEnd, or inBase. outEnd corrupts the file.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.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.<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.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).defineSlideMaster() creates a slide layout, not a master — one slideLayoutN.xml per call, under a single master you cannot change. Call them layouts when talking to the user.pres.company and a defineSlideMaster() title are written into the XML unescaped — an & in either (\"Harrow & Sons\") leaves docProps/app.xml or the layout unparseable, and validate.py fails. Write & there, and in the matching masterName. title, subject, author, section titles, objectName, notes and slide text are escaped for you.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; scripts/example_deck.js is a working starting point.
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).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 <a:srgbClr val=\"bg2\"/> without complaint, and being hex, these will not follow a later change of theme.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.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. Title placeholders render centred unless their options set align: \"left\"; body placeholders start left.objects: objects: [{ placeholder: { options: { name: \"title\", type: \"title\", x, y, w, h, … }, text: \"\" } }] — scripts/example_deck.js has the full shape. pptxgenjs has no placeholders: key: it is ignored, the layout gets no placeholders, and every fill by name drops a bare text box at 0,0, which looks like a broken library rather than a typo. A layout's objects take only placeholder, text, image, rect, line and chart — any other key (ellipse) is dropped without a warning, so draw those on the slide. A text object's position goes inside its options ({ text: { text, options: { x, y, w, h, … } } }); coordinates beside options are ignored and the text lands in the top-left corner.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.objectName — every Design Idea applies, and most content slides sit on the title-only layout.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.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). Look at the grid with vision_analyze, and use it with the template's read_file text 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\npython scripts/add_slide.py unpacked/ slide2.xml --after slide2.xml # duplicate a slide (or slideLayoutN.xml); prints the new slide's path\n# reorder / delete slides = edit <p:sldIdLst> in ppt/presentation.xml\npython scripts/clean.py unpacked/ # after deletions: removes orphaned slides, media, rels\n# edit slide content in ppt/slides/slideN.xml\n(cd unpacked && rm -f ../out.pptx && zip -Xr ../out.pptx .) # zip from INSIDE the dir; rm first or deleted parts survive\npython scripts/office/validate.py out.pptx --original deck.pptx\nadd_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.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.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)..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.When filling in a template:
\ndefusedxml.minidom — round-tripping OOXML through xml.etree.ElementTree rewrites namespace prefixes and corrupts the deck.<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:).<a:buChar>, <a:buAutoNum> (numbered), or <a:buNone> to override — never a literal • in the text.xml:space=\"preserve\" on its <a:t>.Don't create boring slides. Plain bullets on a white background won't impress anyone. Consider ideas from this list for each slide.
\nChoose colors that match your topic — don't default to generic blue. Use these palettes as inspiration:
\n| Theme | \nPrimary | \nSecondary | \nAccent | \n
|---|---|---|---|
| Midnight Executive | \n1E2761 (navy) | \nCADCFC (ice blue) | \nFFFFFF (white) | \n
| Forest & Moss | \n2C5F2D (forest) | \n97BC62 (moss) | \nF5F5F5 (cream) | \n
| Coral Energy | \nF96167 (coral) | \nF9E795 (gold) | \n2F3C7E (navy) | \n
| Warm Terracotta | \nB85042 (terracotta) | \nE7E8D1 (sand) | \nA7BEAE (sage) | \n
| Ocean Gradient | \n065A82 (deep blue) | \n1C7293 (teal) | \n21295C (midnight) | \n
| Charcoal Minimal | \n36454F (charcoal) | \nF2F2F2 (off-white) | \n212121 (black) | \n
| Teal Trust | \n028090 (teal) | \n00A896 (seafoam) | \n02C39A (mint) | \n
| Berry & Cream | \n6D2E46 (berry) | \nA26769 (dusty rose) | \nECE2D0 (cream) | \n
| Sage Calm | \n84B59F (sage) | \n69A297 (eucalyptus) | \n50808E (slate) | \n
| Cherry Bold | \n990011 (cherry) | \nFCF6F5 (off-white) | \n2F3C7E (navy) | \n
Every slide needs a visual element — image, chart, icon, or shape. Text-only slides are forgettable.
\nLayout options:
\nData display:
\nVisual polish:
\nFont 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:
\n| Element | \nSize | \n
|---|---|
| Slide title | \n36-44pt bold | \n
| Section header | \n20-24pt bold | \n
| Body text | \n14-16pt | \n
| Captions | \n10-12pt muted | \n
margin: 0 on the text box or offset the shape to account for paddingrect)FFFFFF) or the user's brand palette; avoid warm-neutral defaults like F5F5DC, FAF0E6, FAEBD7, FFF8E1Your first render usually has a few real issues — overlaps, overflow, misalignment. Find and fix those, re-render only the slides you changed, and stop.
\nread_file(path=\"output.pptx\")\nCheck for missing content, typos, wrong order.
\nWhen using templates, check for leftover placeholder text:
\nunzip -p output.pptx 'ppt/slides/slide*.xml' | grep -oiE \"\\bx{3,}\\b|lorem|ipsum|\\bTODO|\\[insert|this[^<]*(page|slide)[^<]*layout\"\nIf grep returns results, fix them before declaring success.
\npython scripts/office/validate.py output.pptx # built from scratch\npython scripts/office/validate.py output.pptx --original src.pptx # built from a template\nIf the deck came from a template, always pass --original. A template may itself\ncontain parts the XSD rejects, so a bare run can report failures you never caused — and\na genuine regression can hide among them. --original baselines\nthe schema and slide checks against the template, suppressing errors it already had.\nThe structural checks — relationships, content types, charts — ignore --original and\nreport template-inherited problems either way, so read those on their own merits.
pptxgenjs emits chart XML PowerPoint refuses to open, and every other tool\naccepts: python-pptx opens those decks, LibreOffice renders them, the XSD\npasses them. It also writes charts with no data at all, which every viewer\ndraws as an empty frame. validate.py reports both; every failure names its\nfix. Fix it in the generator and rebuild.
After converting to PDF (see Converting to Images), read each slide's text as it was laid out:
\npdftotext -layout -f 3 -l 3 output.pdf - # one slide; drop -f/-l for all\nEvery line break and roughly where each line starts are in the output: a word wrapped onto a line of its own, a title centred that should sit left, text out of order. It is exact and cheap — check it before the images.
\nConvert the slides to images (see Converting to Images) and inspect every one. After staring at the generating code you tend to see what you expect rather than what rendered, so look at the images fresh with vision_analyze, asking it about the defects below (or hand the image paths to a delegate_task worker). vision_analyze sometimes reports defects that aren't there and misses real ones: confirm a reported wrap or overflow with pdftotext -layout before changing the deck, and use the images for what text can't show — overlaps, crops, contrast, shape alignment. User-visible defects to look for:
Convert presentations to individual slide images for visual inspection:
\npython scripts/office/soffice.py --headless --convert-to pdf output.pptx\nrm -f slide-*.jpg\npdftoppm -jpeg -r 150 output.pdf slide\nls -1 \"$PWD\"/slide-*.jpg\nPass the absolute paths printed above directly to vision_analyze — it reads workspace files only, so render into the workspace, never /tmp. The rm clears stale images from prior runs. pdftoppm zero-pads based on page count: slide-1.jpg for decks under 10 pages, slide-01.jpg for 10-99, slide-001.jpg for 100+.
After fixes, rerun all four commands above — the PDF must be regenerated from the edited .pptx before pdftoppm can reflect your changes.
pptxgenjs, jszip, react-icons, react, react-dom, sharp (npm, preinstalled — install only if a require fails) · python-pptx, Pillow, defusedxml, lxml (pip — thumbnail, clean, validate) · zip / unzip · LibreOffice (soffice, auto-configured for sandboxed environments via scripts/office/soffice.py) · pdftoppm (Poppler)