PPTX

PPTX

Build or edit a PowerPoint deck and write it into the task directory (e.g. acme_q4/acme_q4_review.pptx). Someone will stand in front of it, or forward it to a colleague who will. That is what the format is for: a deck is a sequence of single claims, each sized to be read from the back of a room. A slide that needs a paragraph is not a slide, it is a page, and it belongs in a report.

This is the right output when the deck itself is the deliverable: an investment committee pack, a diligence readout, a board update, an earnings walkthrough. It is the wrong output for anything the reader will study alone at their own pace (that is html-report) and for anything they will change numbers in (that is xlsx).

User preferences override these defaults. A house template, a brand palette, a required title slide, a fixed section order: those outrank every rule here. If the user hands you a deck to work in, work in it and match what is already there. The rules below are for when nothing has been specified.

Decide: Which Output?

Workflow

1. Outline first, one message per slide. Write the outline before any code, as ## Slide N headings each carrying one declarative sentence: the claim the slide makes, not its topic. "Revenue grew 21 percent on flat headcount" is a slide. "Revenue" is a filing cabinet. If you cannot write the sentence, you do not have the slide yet.
2. Write a build script, <task>/build_<name>.js, and run it with NODE_PATH=$(npm root -g) node <task>/build_<name>.js. Never assemble a deck through ad-hoc calls. The script is the source of truth; when the user asks for a change, edit the script and rerun.
3. Audit the file, not the script. python .agents/skills/pptx/scripts/check.py <task>/<name>.pptx --strict reads what the file contains, including the position a placeholder inherits from its layout, and reports shapes off the slide, boxes covering each other, overflowing text, fonts and placeholders. It compares the slide's own shapes, so branding that lives on the layout or the master is something only the render in step 4 will show you covered. Fix every fail; for every warn, either fix it or write the one line in the delivery that says why it stands.
4. Render and look: python .agents/skills/pptx/scripts/render.py <task>/<name>.pptx --montage, then view montage.png. This is not optional. Clipped text, a legend over a bar, a title that jumps, one slide twice as dense as its neighbours: all of it is visible here and nowhere else.
5. Fix in the build script, never in the .pptx, then rerun steps 2 to 4 until check.py passes and the render looks right.
6. Deliver the .pptx and the .js beside it, and say in the reply what each slide claims.

Design Rules

Geometry. 16:9 (LAYOUT_WIDE, 13.333 x 7.5 in) unless the user's screen is not. The 0.6 in margin is the left and right content margin, so content spans 12.13 in; vertically each band sits at the y below, from the title at 0.45 to the footer band ending at 7.25. One geometry for every content slide:

Write that as one function in the build script and call it for every slide. A title that moves by a tenth of an inch between slides reads as a flicker when the deck is clicked through, and check.py reports it.

One idea per slide. The title states the finding. The body supports it. If the body supports two findings, that is two slides. Three bullets is a good slide, six is a document, and nine is a filing.

Type. Two families at most, and one is usually enough. Sizes:

Nothing below 10pt, ever, and nothing below 14pt in a table. A number small enough to need leaning in is a number nobody checks.

Budgets check.py holds you to. Its overflow estimate assumes an average glyph 0.50 em wide (0.54 bold) and 1.2 line spacing, so a box fits about width_in * 72 / (pt * 0.5) characters per line: a 28pt bold title across the 12.13 in content width is one line up to about 56 characters, and the 0.60 in title band holds exactly one. Write the finding in under 56 characters or drop to 24pt. The checker takes the largest text in the top 30 percent of the slide (2.25 in) as the title when there is no title placeholder, which is every pptxgenjs deck, so a 40pt number in that band is read as a wandering title: big numbers sit below 2.25 in. Page numbers are a 10pt addText box in the footer band, never slide.slideNumber, which ignores fontSize and renders at 18pt in a box too short for it.

Fonts. Arial, Calibri, Cambria, Times New Roman and Courier New each have a metric-compatible clone installed here (Liberation Sans, Carlito, Caladea, Liberation Serif, Liberation Mono), so the render you inspect breaks its lines exactly where PowerPoint will. Georgia, Verdana, Tahoma, Trebuchet MS and anything else do not: they render substituted, so the layout you checked is not the layout the reader gets. Set fontFace explicitly on every text element; a run with no font takes whatever the theme hands it.

Colour. One accent, used for one meaning. Everything else is ink, grey, and paper.

Green and red mean gain and loss and nothing else. Never encode a category in a colour that already means a direction.

Speaker notes when the user will present, or when they asked. One or two sentences per slide saying what to say, not a transcript of the slide. check.py --require-notes enforces the presence, not the quality.

Build a New Deck

pptxgenjs 4.0.1 is installed globally, so the script needs NODE_PATH=$(npm root -g).

const PptxGenJS = require("pptxgenjs");

const INK = "1A1A1A", MUTED = "5A5A5A", RULE = "D8D5D0", ACCENT = "1F4E79";
const FONT = "Arial", M = 0.6, W = 13.333, CONTENT_W = W - 2 * M;

const pptx = new PptxGenJS();
pptx.layout = "LAYOUT_WIDE";

// One geometry for every content slide, so the title never moves.
function contentSlide(title, kicker) {
  const slide = pptx.addSlide();
  slide.background = { color: "FFFFFF" };
  slide.addText(title, { x: M, y: 0.45, w: CONTENT_W, h: 0.6,
    fontFace: FONT, fontSize: 28, bold: true, color: INK, valign: "middle" });
  slide.addText(kicker, { x: M, y: 1.05, w: CONTENT_W, h: 0.35,
    fontFace: FONT, fontSize: 14, color: MUTED, valign: "top" });
  slide.addShape("rect", { x: M, y: 1.42, w: CONTENT_W, h: 0.02, fill: { color: RULE } });
  return slide;
}

const s = contentSlide("Revenue grew 21 percent on flat headcount", "Three findings drive the FY2026 view");
s.addText(
  [
    { text: "Q4 revenue of $1,240mm beat consensus by 3.4 percent.", options: { bullet: true } },
    { text: "Gross margin held at 64.2 percent on a heavier hardware mix.", options: { bullet: true } },
    { text: "Net retention of 118 percent carries half the FY2026 plan.", options: { bullet: true } },
  ],
  { x: M, y: 1.9, w: CONTENT_W, h: 2.6, fontFace: FONT, fontSize: 18, color: INK,
    lineSpacingMultiple: 1.4, valign: "top" }
);
s.addNotes("Do not read the bullets out; the room has already read them. Lead with the margin point.");

pptx.writeFile({ fileName: "acme_q4/acme_q4_review.pptx" })
  .then(() => console.log("written"));         // the check runs on the file: see step 3

Geometry is checked on the written file by check.py, which reads the real slide XML rather than the build script's intent. A shape crossing a slide edge, or two text boxes covering each other by more than 0.1 in in both directions, is a fail. Fix every one in the script and rebuild.

Charts stay native

addChart writes a real chart part that the reader can click into, retheme, and read numbers off. A picture of a chart is a dead end for them and blurs at any zoom.

slide.addChart(
  pptx.ChartType.bar,
  [{ name: "Revenue ($mm)", labels: ["Q1", "Q2", "Q3", "Q4"], values: [980, 1035, 1128, 1240] }],
  { x: 0.6, y: 1.75, w: 7.4, h: 4.6,
    barDir: "col", chartColors: [ACCENT], showLegend: false, showValue: true,
    dataLabelFontFace: FONT, dataLabelFontSize: 12, dataLabelColor: INK,
    catAxisLabelFontFace: FONT, catAxisLabelFontSize: 12, catAxisLabelColor: MUTED,
    valAxisLabelFontFace: FONT, valAxisLabelFontSize: 12, valAxisLabelColor: MUTED,
    valAxisMaxVal: 1400, valGridLine: { color: RULE, style: "solid", size: 1 },
    catGridLine: { style: "none" }, valAxisLineShow: false, catAxisLineShow: false }
);

• Series data is [{ name, labels, values }], one object per series, labels identical across series.

• One series: pass one colour. chartColors with several entries colours each bar separately, which looks like four categories where there is one.

• Units go in the kicker or the axis title, not on every label. Turn the legend off when there is one series.

• pptx.ChartType.bar with barDir: "col" is vertical, "bar" is horizontal. line, pie, doughnut, area, scatter are the rest of the useful set.

• A combo chart (bars for one series, a line for another) is an array of { type, data, options } in place of the single type, with the shared geometry and axis options in the second argument:

  slide.addChart(
    [{ type: pptx.ChartType.bar,  data: [{ name: "Revenue ($B)", labels, values: revenue }], options: { chartColors: [ACCENT], barDir: "col" } },
     { type: pptx.ChartType.line, data: [{ name: "FCF ($B)", labels, values: fcf }], options: { chartColors: [SERIES2], lineSize: 3, lineDataSymbol: "circle" } }],
    { x: 0.6, y: 1.75, w: 7.3, h: 4.7, showLegend: true, legendPos: "b", legendFontSize: 12,
      catAxisLabelFontSize: 12, valAxisLabelFontSize: 12, valGridLine: { color: RULE, style: "solid", size: 1 } }
  );

• Reach for an image only when the chart type genuinely does not exist here (a waterfall, a slope chart, a small-multiple grid). Then say in the reply that it is an image.

Put the takeaway beside the chart in words. A chart with no sentence next to it makes the room do the work.

Tables

const head = { fill: { color: ACCENT }, color: "FFFFFF", bold: true };
slide.addTable(
  [[{ text: "Segment", options: head }, { text: "Q4 revenue", options: head }],
   ["Platform", "742"],
   [{ text: "Total", options: { bold: true } }, { text: "1,240", options: { bold: true } }]],
  { x: M, y: 1.9, w: CONTENT_W, colW: [4.6, 7.53], fontFace: FONT, fontSize: 14,
    color: INK, rowH: 0.42, valign: "middle", border: { type: "solid", pt: 1, color: RULE } }
);

A table is as tall as its rows: rowH times the row count, whatever h says, and that sum is what the geometry checks measure. Keep y plus the sum inside the content band.

Six rows and four columns is a slide. Twelve rows is a handout, so cut it to the rows that carry the argument and put the full table in an appendix slide or an xlsx. Right-align numbers, put units in the header, and state totals rather than implying them.

Editing an Existing Deck

Never rebuild a human's deck to change three words. Their master, layouts, theme, and every slide you are not touching are work you would be throwing away, and rebuilding loses the parts nobody documented. Open it with python-pptx and write into it.

from pptx import Presentation
from pptx.util import Inches, Pt

prs = Presentation("acme_q4/client_deck.pptx")

def set_text(shape, new_text):
    """Replace a shape's words and keep its formatting.

    The first run carries the font, size and colour, so writing into it and
    dropping the rest preserves the look without having to know what it is.
    `shape.text = "..."` throws all of that away.
    """
    frame = shape.text_frame
    paragraph = frame.paragraphs[0]
    if not paragraph.runs:
        paragraph.add_run()
    paragraph.runs[0].text = new_text
    for run in paragraph.runs[1:]:
        run._r.getparent().remove(run._r)
    for extra in frame.paragraphs[1:]:
        extra._p.getparent().remove(extra._p)

slide = prs.slides[3]
set_text(slide.shapes.title, "Segment detail, restated")

# A new slide comes from a layout the deck already has, so it inherits the design.
layout = next(l for l in prs.slide_layouts if l.name == "Title and Content")
new = prs.slides.add_slide(layout)
new.shapes.title.text = "FY2026 bridge"
new.placeholders[1].text_frame.text = "Volume carries 14 of the 21 points."

prs.save("acme_q4/client_deck_v2.pptx")

Read the deck first: python .agents/skills/pptx/scripts/extract.py deck.pptx gives every slide's text, notes, tables, charts, and the shape names and coordinates you will write into. markitdown deck.pptx is faster for prose alone but drops every position, so it answers "what does this say" and never "which box do I write into". A legacy .ppt opens with python -c "import anydoc,sys; print(anydoc.to_markdown(sys.argv[1]))" old.ppt for the same read-only view (never pass ocr="hosted", which uploads the file to an external service); to edit one, convert it with soffice --headless --convert-to pptx old.ppt and start from the .pptx.

What a python-pptx save preserved when it was measured, on one six-slide deck with a chart, a table and notes: the theme part came back byte for byte, the slide parts that were not edited came back with the same elements, attributes and order (differing only in the whitespace between tags), and the native chart kept its series values. Two parts were rewritten and both are harmless: [Content_Types].xml is rebuilt from the parts present, and a relationship target is normalised from an absolute to a relative path. That is a measurement of one deck, not a guarantee for yours, so prove it on your own edit:

python3 -c "
import zipfile
a, b = zipfile.ZipFile('before.pptx'), zipfile.ZipFile('after.pptx')
print([n for n in sorted(set(a.namelist()) & set(b.namelist()))
       if not n.endswith('/') and a.read(n) != b.read(n)])"

Then render both with render.py and compare the slides you did not touch. That comparison is mandatory, not a formality: a part that survives the byte diff can still come out different once a renderer lays it out. Rules that follow:

• Match what is there. Read a neighbouring slide's fonts, sizes and colours from extract.py and reuse them. Do not restyle a deck the user did not ask you to restyle.
• Placeholders inherit their position from the layout. Reading shape.left gives the inherited value; writing to it pins the shape and ends the inheritance, so leave it alone unless moving it is the task.
• A run's font.size of None means inherited, not 18pt. Do not "fix" it by setting a size.
• There is no copy-a-slide. Add a slide from the same layout and re-add the content. There is no delete either; remove the sldId from prs.slides._sldIdLst when you must.
• Chart data: chart.replace_data(CategoryChartData(...)) refreshes the numbers and keeps the formatting. Deleting and re-adding the chart loses it.
• Rerun check.py and render.py on the edited file. An edit is a deck change like any other.