Document PPTX

Boundary: when the claude.ai Slides artifact type or the official Anthropic pptx skill is available, prefer it for plain create/edit, generic template fill and visual QA. Use this skill for its specialist lanes:

• template inspection before automation (layouts, placeholder idx, shape names, OOXML parts)
• designer-owned template fills with PPTX-Automizer
• speaker-note extraction and damaged-deck inspection
• accessibility and EN 301 549 review

Quick Reference

Job	Default	Notes
Inspect a template before any fill	scripts/pptx_inventory.py --json	Layout names, placeholder idx and type, shape names
Inspect a damaged deck or its parts	scripts/pptx_ooxml_inspect.py	Broken relationships, missing targets, repair dialogs
Extract or back up speaker notes	scripts/pptx_extract_notes.py	Markdown or JSON
Fill a designer-owned template	PPTX-Automizer	Named-element replacement only (chart data, text, table, image)
Python reporting or extraction	python-pptx	Standard charts, notes, placeholders
JS/TS or browser export	PptxGenJS	Real combo charts; 16:9 default layout

Scripts And Exit Codes

Script	0	1	2
pptx_ooxml_inspect.py	No broken relationship targets	Broken targets found (gate). --report-only exits 0 for well-formed packages with broken targets	File missing, invalid package or malformed relationship part
pptx_inventory.py / pptx_extract_notes.py	Written	n/a	File missing, unreadable, or not a .pptx

Decision Rules

• Template first or from scratch. Use the branded template when the deck goes to an external audience, brand or legal review is in the path, or the request names "our template". Build from scratch for internal drafts, exploratory mock-ups or data-shaped reports where speed matters more than branding. Never guess brand colours, fonts or layout names when a template exists: inventory it first. With no template and no brand requirement, a clean unbranded deck beats an invented corporate look.
• PPTX-Automizer only for narrow fills. It merges named elements into a designer-owned structure; it is not a general slide generator.
• Resolve layouts by name, every time. Layout indices are not portable between templates, and designers reorder or rename layouts between versions.
• Guard placeholders by idx set. 1 in slide.placeholders is always False; test against {ph.placeholder_format.idx for ph in slide.placeholders}. See references/pptx-template-branding.md.
• One takeaway per slide, and chart data traceable to one source of truth with units, timeframe and source.
• Accessibility is part of authoring: titles, reading order, contrast and alt text, not a final pass.

Known Limits

• python-pptx has no animation API (no build or entrance effects) and no slide-transition API. Both need direct OOXML <p:timing>/<p:transition> edits; see references/pptx-animations-transitions.md before promising motion.

• python-pptx cannot create a true combo chart (column plus line); it has no multi-plot chart constructor. Fill a template combo chart with replace_data, or use PptxGenJS.

• python-pptx has no gradient-fill API and no supported way to edit theme colours (theme1.xml). Both need direct XML edits with a backup first.

• The colour class is RGBColor (from pptx.dml.color), not RgbColor; the wrong case raises ImportError.

• Default slide sizes differ: python-pptx's default template is 10 × 7.5 in (4:3), PptxGenJS's default is 10 × 5.625 in (16:9). Check every shape and chart against the target size (y + h <= slide height); positions copied from a 4:3 example run off a 16:9 slide.

• PptxGenJS has no slide-transition or auto-advance option; slide.transition / advanceAfter are silently ignored. Write <p:transition> OOXML instead.

• PPTX-Automizer's modifyElement(selector, callback) takes modification callbacks (ModifyTextHelper.setText(...), ModifyTableHelper.setTable(...), ModifyChartHelper.setChartData(...)), not an options object like { text: ... }.

• Blind template edits can break timing, media or repairability. Keynote or Google Slides opening a file cleanly does not confirm PowerPoint compatibility, and the reverse is also true.

• Library behaviour changes between releases. Re-test a claimed API gap or default against the installed version before relying on it, and mark it unverified when you cannot.

Workflow

1. Classify the job: fresh deck, template fill, notes extraction, or repair.
2. Build the slide narrative before writing slide code (assets/slide-narrative-template.md).
3. Inspect the template (pptx_inventory.py --json, pptx_ooxml_inspect.py --json) before any automation change.
4. Generate or edit, then run the release gate below.

Rendered Slide Release Gate

After the final save, reopen the deck and inventory slide count, layout names, placeholders, media relationships, chart data, and speaker notes. Render every slide to images or PDF in the declared delivery target and inspect for clipped text, font substitution, objects outside the slide, broken chart labels, low-resolution images, and unintended blank placeholders. Require an actual PowerPoint pass when PowerPoint fidelity or accessibility is an acceptance criterion; otherwise use the available target renderer and mark PowerPoint fidelity unverified.

Compare charts and headline figures with the source data after rendering, not only in the generation code. For template edits, confirm that masters and theme relationships still resolve and that the declared target viewer opens the file without a repair dialog. Record any viewer-specific variance instead of treating one viewer as proof for another.

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
• references/deck-narrative-and-visual-patterns.md — Load when choosing a deck structure, persuasion arc, per-slide layout, slide type scale, or chart for a slide
• references/extraction-stack.md — Load when picking an extraction tool (native parse vs Docling vs OCR) for a new LLM/RAG pipeline
• 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

Learnings Loop

When prior decisions or pitfalls are relevant, consult learnings.consolidated.md if present; use learnings.md only for needed history or as the available fallback. Otherwise skip both.

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.