PowerPoint Python
Engineer a presentation as a semantic and visual artifact built on a multipart
PresentationML package. A file that saves and reopens can still be visually
wrong or can have lost required unsupported behavior.
Boundary
Use python-pptx for supported .pptx creation, inspection, and minimal editing.
Use ZIP/XML inspection for package and preservation risk. Treat .pptm as
inspection-first and preservation-sensitive. This skill never executes VBA,
actions, media, linked programs, add-ins, or OLE objects.
Stop and require an authorized PowerPoint-runtime path for .ppt, native
open/save or PDF export, native rendering, font-substitution diagnostics,
animations/transitions whose behavior matters, media playback, accessibility
checker evidence, macro execution, add-ins, UI automation, or exact unsupported
feature copying. Read boundaries and routing.
Choose the implementation from the operation
| Intent |
Mechanism |
Gate |
| Create ordinary deck |
python-pptx |
Use a verified template contract. |
| Populate approved template |
python-pptx placeholders |
Resolve layout and placeholder identity first. |
| Inspect semantics |
python-pptx plus package inventory |
Unsupported parts require ZIP/XML evidence. |
| Edit existing content |
Smallest supported python-pptx mutation |
Preflight and semantic diff are mandatory when preservation matters. |
| Change unsupported OOXML |
Narrow tested lxml helper |
Stop unless exact part ownership and preservation can be proven. |
| Render or execute behavior |
External renderer or PowerPoint runtime |
python-pptx is not a renderer or application runtime. |
| Calculate metrics |
Domain/data layer |
Pass resolved content to the renderer. |
| Complex analytical chart |
Approved plot renderer to image |
Use native chart only when editability is contractual. |
Inspect installed versions and required signatures with python scripts/inspect_powerpoint_env.py; read API grounding.
Ordered workflow
- Recover the presentation contract: audience, objective, decision/takeaway,
source/provenance, slide roles and order, template, aspect ratio, editable
versus static elements, notes, fonts, accessibility, preservation, renderer,
visual QA, destination, and delivery evidence.
- For an existing file, preserve the source and run
python scripts/inspect_presentation.py SOURCE. Inventory macros, timing,
transitions, SmartArt/diagrams, comments, external links, actions, OLE,
embeddings, unusual media, custom XML, notes, and unknown parts before save.
- Run
python scripts/inspect_template.py TEMPLATE. Resolve layouts by
discovered semantic name and verified placeholder idx, type, and geometry;
never assume a layout or placeholder position.
- Resolve analysis and content into typed objects, then build a semantic
DeckSpec-like model. Low-level shape calls consume that model; they do not
invent narrative or business calculations. Read presentation
contracts.
- Render from the approved template using its masters, layouts, placeholders,
theme, and typography. A generic bundled template is allowed only when the
request explicitly permits a generic blank presentation.
- Save to a temporary sibling, never over the source by default. Reopen the
output independently.
- Run
python scripts/validate_presentation.py OUTPUT --contract CONTRACT.json
when a machine contract exists. For edits, also run python scripts/diff_presentations.py BEFORE AFTER and explain every difference.
- If a renderer is available, render every consequential slide and perform
visual QA. If fidelity is mandatory and no acceptable renderer exists, stop.
- Report only evidence actually established:
GENERATED, REOPENED,
PACKAGE_VALIDATED, SEMANTICS_VALIDATED, PRESERVATION_VALIDATED,
RENDERED, VISUAL_QA_PASSED, POWERPOINT_NATIVE_OPENED,
POWERPOINT_NATIVE_RENDERED, and ACCESSIBILITY_CHECKED.
Template, geometry, and text invariants
- Prefer template-native placeholders over freeform shapes. A slide inherits
from a layout, which inherits from a master; placeholder
idx connects the
slide placeholder to its layout definition. Read templates, layouts, and
placeholders.
- Derive slide dimensions. Centralize
Point, Size, Rect, margins, grid,
gaps, split, alignment, distribution, containment, and intersection helpers.
Reject negative/zero geometry, off-slide content, accidental overlap,
title/body/footer collisions, distorted images, and unexplained alignment or
layering drift. Mark intentional overlap explicitly. Read geometry and
layout.
- Preserve text formatting at the narrowest paragraph/run level. Do not use
shape.text = ... when it would destroy meaningful formatting. Inherit theme
typography; do not hard-code fonts everywhere. Treat overflow as a content or
layout failure: shorten, split, or restructure before using fit_text() and
never shrink below the presentation contract. Read text and
typography.
- Treat fonts available locally, font references inspected, and PowerPoint
substitution checked as different states. Local rendering with a corporate
font does not prove recipient fidelity.
Content objects
- Images require semantic role, source, target rectangle,
fit/fill/contain/
cover crop policy, resolution policy, and accessibility intent. Never
stretch by supplying arbitrary width and height. Read images.
- Use native charts when recipients must edit data; otherwise prefer an
externally rendered image for exact analytical layout. Chart inputs, order,
units, number formats, axes, labels, and embedded workbook are contractual.
Read charts.
- Tables communicate a bounded comparison, not arbitrary dataframes. Aggregate
elsewhere, make units explicit, align numbers, distinguish totals, and keep
pagination widths identical. Read tables.
- Preserve notes and inspect hyperlinks, actions, relationships, media, and
embedded objects without following or activating them. Read notes, links,
and media and security.
Existing-presentation preservation
Mutate the smallest supported region and save to a new destination. Directly
inspect parts and relationships for masters/layouts/themes, notes, charts,
embeddings, media, comments/people/tags, diagrams, timing/transitions, VBA,
custom XML, properties, and unknown relationships. Unknown or required
unsupported content blocks a blind round-trip. Read OOXML preservation
and existing presentations.
For .pptm, detect the macro-enabled content type and vbaProject.bin, hash it
before and after, preserve the macro-enabled format, and never execute it.
Report VBA_PRESENT, VBA_HASH_VERIFIED, or
VBA_PRESERVATION_UNVERIFIED; never report VBA_EXECUTED.
Do not copy slides between presentations by cloning slide XML. Slides own
relationships to layouts, media, charts, notes, workbooks, links, and diagrams.
Reconstruct supported semantic content in the destination or use an authorized
PowerPoint-native operation when exact copying is required.
Accessibility and rendering evidence
Use meaningful unique titles, logical object creation/order, alt text for
meaningful visuals, decorative classification where supported, understandable
links, simple tables, adequate contrast, and non-color-only encoding. A narrow
tested OOXML helper is allowed when the public API cannot express a required
property. Never claim Microsoft's checker passed unless it ran. Read
accessibility.
After rendering, inspect clipping, overflow, minimum font size, overlap,
canvas bounds, image distortion, alignment/margins, wrapping, orphan labels,
chart labels/legends, hierarchy, footnotes/footers, title placement, fonts, and
blank space. Visual diffs diagnose regression but do not prove semantic
equivalence. Read rendering and visual QA.
Completion
Do not declare a consequential task complete until the correct template and
dimensions were used; layout/placeholder identity is proven; slide roles,
titles, order, notes, charts/tables, images, geometry, and active-content policy
match the contract; the source remains intact; required package parts and hashes
survive; the output reopens; structural and semantic checks pass; rendering and
visual status are explicit; and project tests pass or skipped checks and their
consequences are reported. Read validation and testing,
performance, and evaluated recipes.
Runtime helpers
- Inspect environment
- Inspect template
- Inspect presentation
- Validate presentation
- Diff presentations
1---2name: powerpoint-python3description: >-4 Use for writing, reviewing, debugging, testing, or optimizing Python code5 that inspects, edits, extracts, validates, preserves, or generates Microsoft6 PowerPoint Open XML presentations, primarily .pptx, using python-pptx,7 PresentationML/OOXML, Pillow, or supporting Python libraries. Trigger on8 slides, masters, layouts, placeholders, shapes, text, pictures, tables,9 charts, notes, themes, hyperlinks, embedded objects, macros, preservation,10 geometry, rendering verification, and presentation package inspection. Do11 not use for .ppt binary files, PowerPoint UI automation, VBA execution,12 slideshow execution, or presentation advice with no Python or file boundary.13argument-hint: "[presentation task, template/preservation requirements, and output contract]"14metadata:15 source: https://skillmd.com/skills/schattenspiegel/powerpoint-python16---1718# PowerPoint Python1920Engineer a presentation as a semantic and visual artifact built on a multipart21PresentationML package. A file that saves and reopens can still be visually22wrong or can have lost required unsupported behavior.2324## Boundary2526Use python-pptx for supported `.pptx` creation, inspection, and minimal editing.27Use ZIP/XML inspection for package and preservation risk. Treat `.pptm` as28inspection-first and preservation-sensitive. This skill never executes VBA,29actions, media, linked programs, add-ins, or OLE objects.3031Stop and require an authorized PowerPoint-runtime path for `.ppt`, native32open/save or PDF export, native rendering, font-substitution diagnostics,33animations/transitions whose behavior matters, media playback, accessibility34checker evidence, macro execution, add-ins, UI automation, or exact unsupported35feature copying. Read [boundaries and routing](references/boundaries.md).3637## Choose the implementation from the operation3839| Intent | Mechanism | Gate |40|---|---|---|41| Create ordinary deck | python-pptx | Use a verified template contract. |42| Populate approved template | python-pptx placeholders | Resolve layout and placeholder identity first. |43| Inspect semantics | python-pptx plus package inventory | Unsupported parts require ZIP/XML evidence. |44| Edit existing content | Smallest supported python-pptx mutation | Preflight and semantic diff are mandatory when preservation matters. |45| Change unsupported OOXML | Narrow tested lxml helper | Stop unless exact part ownership and preservation can be proven. |46| Render or execute behavior | External renderer or PowerPoint runtime | python-pptx is not a renderer or application runtime. |47| Calculate metrics | Domain/data layer | Pass resolved content to the renderer. |48| Complex analytical chart | Approved plot renderer to image | Use native chart only when editability is contractual. |4950Inspect installed versions and required signatures with `python51scripts/inspect_powerpoint_env.py`; read [API grounding](references/api-grounding.md).5253## Ordered workflow54551. Recover the presentation contract: audience, objective, decision/takeaway,56 source/provenance, slide roles and order, template, aspect ratio, editable57 versus static elements, notes, fonts, accessibility, preservation, renderer,58 visual QA, destination, and delivery evidence.592. For an existing file, preserve the source and run `python60 scripts/inspect_presentation.py SOURCE`. Inventory macros, timing,61 transitions, SmartArt/diagrams, comments, external links, actions, OLE,62 embeddings, unusual media, custom XML, notes, and unknown parts before save.633. Run `python scripts/inspect_template.py TEMPLATE`. Resolve layouts by64 discovered semantic name and verified placeholder `idx`, type, and geometry;65 never assume a layout or placeholder position.664. Resolve analysis and content into typed objects, then build a semantic67 `DeckSpec`-like model. Low-level shape calls consume that model; they do not68 invent narrative or business calculations. Read [presentation69 contracts](references/presentation-contract.md).705. Render from the approved template using its masters, layouts, placeholders,71 theme, and typography. A generic bundled template is allowed only when the72 request explicitly permits a generic blank presentation.736. Save to a temporary sibling, never over the source by default. Reopen the74 output independently.757. Run `python scripts/validate_presentation.py OUTPUT --contract CONTRACT.json`76 when a machine contract exists. For edits, also run `python77 scripts/diff_presentations.py BEFORE AFTER` and explain every difference.788. If a renderer is available, render every consequential slide and perform79 visual QA. If fidelity is mandatory and no acceptable renderer exists, stop.809. Report only evidence actually established: `GENERATED`, `REOPENED`,81 `PACKAGE_VALIDATED`, `SEMANTICS_VALIDATED`, `PRESERVATION_VALIDATED`,82 `RENDERED`, `VISUAL_QA_PASSED`, `POWERPOINT_NATIVE_OPENED`,83 `POWERPOINT_NATIVE_RENDERED`, and `ACCESSIBILITY_CHECKED`.8485## Template, geometry, and text invariants8687- Prefer template-native placeholders over freeform shapes. A slide inherits88 from a layout, which inherits from a master; placeholder `idx` connects the89 slide placeholder to its layout definition. Read [templates, layouts, and90 placeholders](references/templates-layouts-placeholders.md).91- Derive slide dimensions. Centralize `Point`, `Size`, `Rect`, margins, grid,92 gaps, split, alignment, distribution, containment, and intersection helpers.93 Reject negative/zero geometry, off-slide content, accidental overlap,94 title/body/footer collisions, distorted images, and unexplained alignment or95 layering drift. Mark intentional overlap explicitly. Read [geometry and96 layout](references/geometry-layout.md).97- Preserve text formatting at the narrowest paragraph/run level. Do not use98 `shape.text = ...` when it would destroy meaningful formatting. Inherit theme99 typography; do not hard-code fonts everywhere. Treat overflow as a content or100 layout failure: shorten, split, or restructure before using `fit_text()` and101 never shrink below the presentation contract. Read [text and102 typography](references/text-typography.md).103- Treat fonts available locally, font references inspected, and PowerPoint104 substitution checked as different states. Local rendering with a corporate105 font does not prove recipient fidelity.106107## Content objects108109- Images require semantic role, source, target rectangle, `fit`/`fill`/`contain`/110 `cover` crop policy, resolution policy, and accessibility intent. Never111 stretch by supplying arbitrary width and height. Read [images](references/images.md).112- Use native charts when recipients must edit data; otherwise prefer an113 externally rendered image for exact analytical layout. Chart inputs, order,114 units, number formats, axes, labels, and embedded workbook are contractual.115 Read [charts](references/charts.md).116- Tables communicate a bounded comparison, not arbitrary dataframes. Aggregate117 elsewhere, make units explicit, align numbers, distinguish totals, and keep118 pagination widths identical. Read [tables](references/tables.md).119- Preserve notes and inspect hyperlinks, actions, relationships, media, and120 embedded objects without following or activating them. Read [notes, links,121 and media](references/notes-links-media.md) and [security](references/security.md).122123## Existing-presentation preservation124125Mutate the smallest supported region and save to a new destination. Directly126inspect parts and relationships for masters/layouts/themes, notes, charts,127embeddings, media, comments/people/tags, diagrams, timing/transitions, VBA,128custom XML, properties, and unknown relationships. Unknown or required129unsupported content blocks a blind round-trip. Read [OOXML preservation](references/ooxml-preservation.md)130and [existing presentations](references/existing-presentations.md).131132For `.pptm`, detect the macro-enabled content type and `vbaProject.bin`, hash it133before and after, preserve the macro-enabled format, and never execute it.134Report `VBA_PRESENT`, `VBA_HASH_VERIFIED`, or135`VBA_PRESERVATION_UNVERIFIED`; never report `VBA_EXECUTED`.136137Do not copy slides between presentations by cloning slide XML. Slides own138relationships to layouts, media, charts, notes, workbooks, links, and diagrams.139Reconstruct supported semantic content in the destination or use an authorized140PowerPoint-native operation when exact copying is required.141142## Accessibility and rendering evidence143144Use meaningful unique titles, logical object creation/order, alt text for145meaningful visuals, decorative classification where supported, understandable146links, simple tables, adequate contrast, and non-color-only encoding. A narrow147tested OOXML helper is allowed when the public API cannot express a required148property. Never claim Microsoft's checker passed unless it ran. Read149[accessibility](references/accessibility.md).150151After rendering, inspect clipping, overflow, minimum font size, overlap,152canvas bounds, image distortion, alignment/margins, wrapping, orphan labels,153chart labels/legends, hierarchy, footnotes/footers, title placement, fonts, and154blank space. Visual diffs diagnose regression but do not prove semantic155equivalence. Read [rendering and visual QA](references/rendering-visual-qa.md).156157## Completion158159Do not declare a consequential task complete until the correct template and160dimensions were used; layout/placeholder identity is proven; slide roles,161titles, order, notes, charts/tables, images, geometry, and active-content policy162match the contract; the source remains intact; required package parts and hashes163survive; the output reopens; structural and semantic checks pass; rendering and164visual status are explicit; and project tests pass or skipped checks and their165consequences are reported. Read [validation and testing](references/validation-testing.md),166[performance](references/performance.md), and [evaluated recipes](references/recipes-core.md).167168## Runtime helpers169170- [Inspect environment](scripts/inspect_powerpoint_env.py)171- [Inspect template](scripts/inspect_template.py)172- [Inspect presentation](scripts/inspect_presentation.py)173- [Validate presentation](scripts/validate_presentation.py)174- [Diff presentations](scripts/diff_presentations.py)