# Python PPTX Generator > Python PPTX Generator workflow skill. Use this skill when the user needs Generate complete Python scripts that build polished PowerPoint decks with python-pptx and real slide content and the operator should preserve the upstream workflow, copied support files, and provenance before merging or handing off. - Skill: `diegosouzapw/python-pptx-generator-2` (Agent Skill, multi-file: 19 files) - Install (CLI): `npx skillmds@latest add diegosouzapw/python-pptx-generator-2` - Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/python-pptx-generator-2/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: diegosouzapw (https://skillmd.com/u/diegosouzapw) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/diegosouzapw/python-pptx-generator-2 --- # Python PPTX Generator ## Overview This skill generates complete Python scripts that build PowerPoint decks with `python-pptx`, including real slide content rather than placeholder-only scaffolds. It preserves the upstream skill identity and provenance while upgrading the workflow into a template-first, execution-focused process that is safer and more reliable in real projects. Use this skill to turn a deck brief into a working `.pptx` generator script that: - opens a branded template when one exists - selects slide layouts deliberately - inserts content through placeholders when possible - builds text with explicit paragraphs and runs - adds charts, tables, and images through supported `python-pptx` APIs - saves output deterministically and performs a reopen smoke test This skill does **not** promise full PowerPoint authoring parity. Do not use it for exact recreation of arbitrary hand-designed slides, complex animations, SmartArt, or effects outside `python-pptx` support. ## When to Use Use this skill when: - the user wants a ready-to-run Python script that creates a `.pptx` file - the user needs slide copy drafted and encoded directly into `python-pptx` - the task requires a real presentation structure, not just an outline - the output should follow a known template, brand deck, or standard slide layout - the operator needs to generate or debug placeholder-aware PowerPoint automation - charts, tables, images, and speaker-ready slide text must be produced from structured inputs Do **not** use this skill when: - the user only wants presentation ideas, headlines, or a non-code outline - the request depends on unsupported PowerPoint features such as SmartArt recreation, animation choreography, or pixel-perfect manual design replication - the user needs live Office automation through PowerPoint itself rather than file-based generation with `python-pptx` ## Operating Table | Situation | Start here | Why it matters | | --- | --- | --- | | Template deck is available | `python scripts/validate-runtime.py path/to/template.pptx` | Inventories slide layouts and placeholder metadata before code generation so the script targets real layout names and placeholder idx values | | Template behavior or API details are unclear | `references/runtime-practices.md` | Summarizes placeholder, text, chart, table, units, and metadata behaviors that commonly cause generation errors | | You need a worked pattern before writing custom code | `examples/implementation-example.md` | Provides a concrete deck brief, slide plan, complete script, and expected output structure | | User brief is incomplete | Workflow Step 1 | Missing layout names, placeholder roles, chart data, or output path will usually degrade deck quality more than model quality does | | Blank-deck fallback is required | Workflow Step 4B | Ensures the script uses explicit measurements and supported APIs without pretending to match a branded template | | Final validation before handoff | Workflow Step 7 | Save, reopen, and report what was generated, what was assumed, and what the reviewer should verify in PowerPoint | ## Workflow ### 1) Collect a deck brief before writing code Do not start by writing `python-pptx` calls blindly. First collect the minimum runtime brief: - presentation goal - audience - desired slide count or slide list - output path - whether a template `.pptx` exists - if a template exists: template path, target layout names, and placeholder roles - title, subtitle, section, and body content for each slide - image paths and where each image should appear - chart requirements: chart type, categories, series labels, values, number formats, axis titles - table requirements: rows, columns, headers, body values, merged-cell expectations - brand constraints: fonts, colors, density limits, and whether the template already enforces them - optional metadata: title, subject, author, keywords If the user provides only a topic, ask for missing content or explicitly state that the script will include drafted slide copy and any assumptions. ### 2) Inspect the template before generating code If a template deck exists, inspect it first: ```bash python scripts/validate-runtime.py path/to/template.pptx ``` Record at least: - slide layout names - which layouts will be used for which slides - placeholder idx values - placeholder names and types - notable geometry for picture or content placeholders This step prevents a common failure mode: syntactically valid code that targets the wrong layout or placeholder. ### 3) Convert the brief into a slide-by-slide plan Before coding, map each slide to: - layout name - title text - body structure - bullet hierarchy - emphasized phrases needing separate runs - data visual or table requirements - image usage - notes about content density Prefer concise, credible slides over stuffing text into placeholders and shrinking fonts until the slide technically fits. ### 4) Generate the script using the correct branch #### 4A) Template-first branch When a branded or existing deck matters, generate code that: - opens `Presentation(template_path)` - resolves the intended slide layout by inspected name, not by guessed numeric position alone - uses title and content placeholders where available - uses placeholder idx values gathered during inspection - reacquires shapes returned by `insert_picture()` or `insert_table()` rather than continuing to use the original placeholder object - keeps coordinates minimal when the template already provides placeholders #### 4B) Blank-deck fallback branch When no template exists, generate code that: - creates `Presentation()` - uses supported built-in layouts intentionally - uses `Inches()`, `Cm()`, and `Pt()` instead of raw EMU integers - positions charts, tables, and images with readable measurements - keeps sizing and spacing deterministic and easy to adjust ### 5) Build text explicitly For non-trivial text, use the text hierarchy deliberately: - clear the text frame when replacing inherited content - create paragraphs for bullet levels or separate logical statements - create runs for mixed emphasis within a paragraph - set font size with `Pt(...)` - only set alignment, margins, and spacing where needed Prefer explicit paragraph/run construction over assigning a large string to `.text` when formatting matters. ### 6) Use supported APIs for data visuals and tables For charts: - require a concrete chart type - require categories and series values - include number formats when percentages, currency, or scaled values matter - label titles and axes only when the brief calls for them For tables: - require dimensions and concrete values - prefer table placeholders in templates when available - otherwise insert a table with explicit dimensions and readable units - treat merged cells and long text as layout risks that may need simplification For images: - use real file paths - keep insertion logic explicit - preserve aspect ratio expectations when the brief or template requires them ### 7) Save and perform a smoke test Every generated script should: - save to the requested output path - reopen the generated file with `Presentation(output_path)` as a basic validity check - print or log a short success message naming the output file At handoff, report: - which template or layout assumptions were used - which placeholders were targeted - any drafted content the model invented from incomplete inputs - any features intentionally left out because `python-pptx` does not support them well ## Troubleshooting ### Problem: The script runs, but content lands in the wrong place Likely cause: - wrong slide layout selected - placeholder idx guessed rather than inspected - placeholder sequence position confused with placeholder idx Fix: - rerun `scripts/validate-runtime.py` - target layouts by inspected name - target placeholders by actual `idx` values, not list order ### Problem: `insert_picture()` or `insert_table()` breaks later code using the same placeholder variable Likely cause: - placeholder insertion can replace the underlying XML element - the original placeholder reference becomes invalid after insertion Fix: - capture the returned object from the insertion call - do not continue using the pre-insert placeholder reference ### Problem: Bullet formatting or mixed emphasis disappears Likely cause: - assigning aggregate `.text` overwrote paragraph/run structure Fix: - call `text_frame.clear()` - rebuild paragraphs and runs explicitly - set paragraph level and run font properties deliberately ### Problem: A chart or table renders poorly or misleadingly Likely cause: - missing categories, malformed series data, missing number formats, or over-dense table inputs Fix: - collect structured input before generation - verify chart type matches the story being told - simplify tables rather than compressing unreadable content ### Problem: Text is clipped or the slide feels crowded Likely cause: - too much content for the chosen layout - brute-force font shrinking used as a fallback Fix: - reduce content density - split content into additional slides - use a more appropriate layout or placeholder - avoid promising a single-slide fit for content that should span multiple slides ### Problem: The generated file saves, but PowerPoint output quality is disappointing Likely cause: - the request needed template-aware design, richer brand rules, or manual finishing beyond library support Fix: - move to a template-first workflow - inspect placeholders before generation - be explicit about scope limits for advanced visual effects ## Additional Resources - `references/runtime-practices.md` — compact execution reference for placeholders, text, charts, tables, units, and metadata - `examples/implementation-example.md` — worked deck brief, slide plan, full script, and expected result shape - `scripts/validate-runtime.py` — template inspection utility for layouts and placeholders Primary documentation used for this workflow: - `python-pptx` quickstart: https://python-pptx.readthedocs.io/en/latest/user/quickstart.html - placeholders: https://python-pptx.readthedocs.io/en/latest/user/placeholders-using.html - text: https://python-pptx.readthedocs.io/en/latest/user/text.html - charts: https://python-pptx.readthedocs.io/en/latest/user/charts.html - tables: https://python-pptx.readthedocs.io/en/latest/user/table.html - presentation API: https://python-pptx.readthedocs.io/en/latest/api/presentation.html - units/utilities: https://python-pptx.readthedocs.io/en/latest/api/util.html - core properties: https://python-pptx.readthedocs.io/en/latest/dev/analysis/pkg-coreprops.html ## Related Skills Use a different or adjacent skill when the task shifts to: - data cleaning or analysis before charts/tables are generated - image creation or editing before deck assembly - presentation review, rewrite, or speaker-note refinement after the `.pptx` script is working - manual visual design polish that depends on PowerPoint features outside `python-pptx` ## Provenance Note This enhanced skill preserves the upstream community skill identity and intent while translating it into a more operational Omni-ready workflow. The goal is not to replace the upstream idea, but to make execution more reliable for real template-driven PowerPoint automation.