powerpoint

PowerPoint Skill

Generates, updates, and manages PowerPoint slide decks using python-pptx with YAML-driven content and styling definitions.

Overview

This skill provides Python scripts that consume YAML configuration files to produce PowerPoint slide decks. Each slide is defined by a content.yaml file describing its layout, text, and shapes. A style.yaml file defines dimensions, template configuration, layout mappings, metadata, and defaults.

SKILL.md covers technical reference: prerequisites, commands, script architecture, API constraints, and troubleshooting. For conventions and design rules (element positioning, visual quality, color and contrast, contextual styling), follow pptx.instructions.md.

Prerequisites

PowerShell

The Invoke-PptxPipeline.ps1 script handles virtual environment creation and dependency installation automatically via uv sync. Requires uv, Python 3.11+, and PowerShell 7+.

Installing uv

If uv is not installed:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# Via pip (fallback)
pip install uv

System Dependencies (Export and Validation)

The Export and Validate actions require LibreOffice for PPTX-to-PDF conversion and optionally pdftoppm from poppler for PDF-to-JPG rendering. When pdftoppm is not available, PyMuPDF handles the image rendering.

The Validate action's vision-based checks require the GitHub Copilot CLI for model access.

# macOS
brew install --cask libreoffice
brew install poppler        # optional, provides pdftoppm

# Linux
sudo apt-get install libreoffice poppler-utils

# Windows (winget preferred, choco fallback)
winget install TheDocumentFoundation.LibreOffice
# choco install libreoffice-still      # alternative
# poppler: no winget package; use choco install poppler (optional, provides pdftoppm)

Copilot CLI (Vision Validation)

The validate_slides.py script uses the GitHub Copilot SDK to send slide images to vision-capable models. The Copilot CLI must be installed and authenticated:

# Install Copilot CLI
npm install -g @github/copilot-cli

# Authenticate (uses the same GitHub account as VS Code Copilot)
copilot auth login

# Verify
copilot --version

Required Files

• style.yaml — Dimensions, defaults, template configuration, and metadata
• content.yaml — Per-slide content definition (text, shapes, images, layout)
• (Optional) content-extra.py — Custom Python for complex slide drawings

Content Directory Structure

All slide content lives under the working directory's content/ folder:

content/
├── global/
│   ├── style.yaml              # Dimensions, defaults, template config, and theme metadata
│   └── voice-guide.md          # Voice and tone guidelines
├── slide-001/
│   ├── content.yaml            # Slide 1 content and layout
│   └── images/                 # Slide-specific images
│       ├── background.png
│       └── background.yaml     # Image metadata sidecar
├── slide-002/
│   ├── content.yaml            # Slide 2 content and layout
│   ├── content-extra.py        # Custom Python for complex drawings
│   └── images/
│       └── screenshot.png
├── slide-003/
│   ├── content.yaml
│   └── images/
│       ├── diagram.png
│       └── diagram.yaml
└── ...

Global Style Definition (style.yaml)

The global style.yaml defines dimensions, template configuration, layout mappings, metadata, and defaults. Color and font choices are specified per-element in each slide's content.yaml rather than centralized in the style file.

See the style.yaml template for the full template, field reference, and usage instructions.

Per-Slide Content Definition (content.yaml)

Each slide's content.yaml defines layout, text, shapes, and positioning. All position and size values are in inches. Color values use #RRGGBB hex format or @theme_name references.

Text contract: markdown-like list lines in textbox.text and shape.text are interpreted as PowerPoint lists during rendering. Unordered markers (-, +, *) become bulleted paragraphs, ordered markers (1., 1)) become auto-numbered paragraphs, and leading indentation maps to paragraph level.

See the content.yaml template for the full template, supported element types, supported shape types, and usage instructions.

Complex Drawings (content-extra.py)

When a slide requires complex drawings that cannot be expressed through content.yaml element definitions, create a content-extra.py file in the slide folder. The render() function signature is fixed. The build script calls it after placing standard content.yaml elements.

See the content-extra.py template for the full template, function parameters, and usage guidelines.

Security Validation

content-extra.py execution is disabled by default. When a slide folder contains one and --allow-scripts is not passed, the build fails with an error naming the file. Pass --allow-scripts to authorize execution after reviewing the script.

When execution is authorized, the build script performs AST-based static analysis before running the file and rejects the patterns below. This analysis is a lint that catches obvious mistakes early. It is not a security boundary: a blocked module reached through an alias is not detected, and pathlib and open are permitted. Authorization is the control.

Allowed imports:

• pptx and all pptx.* submodules
• Safe standard-library modules (e.g., math, copy, json, re, pathlib, collections, itertools, functools, typing, enum, dataclasses, decimal, fractions, string, textwrap)

Blocked imports:

• subprocess, os, shutil, socket, ctypes, signal, multiprocessing, threading, http, urllib, ftplib, smtplib, imaplib, poplib, xmlrpc, webbrowser, code, codeop, compileall, py_compile, zipimport, pkgutil, runpy, ensurepip, venv, sqlite3, tempfile, shelve, dbm, pickle, marshal, importlib, sys, telnetlib
• Any third-party package not on the allowlist

Blocked builtins:

• Dangerous: eval, exec, __import__, compile, breakpoint
• Indirect bypass: getattr, setattr, delattr, globals, locals, vars
• Attribute-form calls onto builtins, os, sys, subprocess, and importlib (for example builtins.eval(...))

--allow-scripts flag:

Pass --allow-scripts to authorize execution of content-extra.py files. Without it, a present script fails the build rather than being skipped, so a deck never silently loses custom drawings. The flag authorizes execution; it does not skip the lint.

This is a behavior change. A deck that previously built with a content-extra.py present now requires --allow-scripts, and a script relying on a blocked import no longer has a bypass.

python scripts/build_deck.py \
  --content-dir content/ \
  --style content/global/style.yaml \
  --output slide-deck/presentation.pptx \
  --allow-scripts

When validation fails, the build raises ContentExtraError with a message identifying the violation and file path.

Script Reference

The full command surface lives in references/script-reference.md: build a deck, build from a template, update specific slides, extract content from an existing PPTX, validate, export slides to images or SVG, dry-run validation, generate theme variants, and embed audio.

Script Architecture

The build and extraction scripts use shared modules in the scripts/ directory:

python-pptx Constraints

• python-pptx does NOT support SVG images. Always convert to PNG via cairosvg or Pillow.
• python-pptx cannot create new slide masters or layouts programmatically. Use blank layouts or start from a template PPTX with the --template argument.
• Transitions and animations are preserved when opening and saving existing files, but cannot be created or modified via the API.
• When extracting content, slide master and layout inheritance means many text elements have no inline styling. Add explicit font properties in content YAML before rebuilding.
• The Export and Validate actions require LibreOffice for PPTX-to-PDF conversion. The PowerShell orchestrator checks for LibreOffice availability before starting and provides platform-specific install instructions if missing.
• Accessing background.fill on slides with inherited backgrounds replaces them with NoFill. Check slide.follow_master_background before accessing the fill property.
• Gradient fills use the python-pptx GradientFill API with GradientStop objects. Each stop specifies a position (0–100) and a color.
• Theme colors resolve via MSO_THEME_COLOR enum. Brightness adjustments apply through the color format's brightness property.
• Template-based builds load layouts by name or index. Layout name resolution falls back to index 6 (blank) when no match is found.

Security Considerations

This skill processes PDF files via PyMuPDF, which wraps the MuPDF C library. MuPDF parses untrusted binary structures (cross-reference tables, stream objects, font definitions) and historical CVEs have shown that memory-safety bugs in C parsers can lead to crashes, memory disclosure, or in rare cases code execution.

Mitigations in place

• scripts/pdf_safety.py validates every PDF (existence, regular-file, size <= 100 MB, %PDF- magic bytes, page count <= 1000) before calling fitz.open().
• All fitz operations are wrapped in safe_open_pdf(), which converts MuPDF exceptions into typed PdfSafetyError subclasses (PdfTooLargeError, PdfInvalidFormatError, PdfTooManyPagesError, PdfParseError, PdfRenderError).
• pymupdf is version-pinned in pyproject.toml (>=1.27.1,<2.0) to track security fixes without silently adopting a major-version API change.

Defense-in-depth note: the 5-byte %PDF- magic check is a necessary but not sufficient guarantee of structural validity. A crafted small file that begins with %PDF- still reaches the MuPDF parser, where memory-safety bugs may exist. Callers MUST keep PyMuPDF patched against the latest advisories (tracked via microsoft/hve-core#1020 / pip-audit) and continue to treat such inputs as untrusted. The PdfSafetyError hierarchy (PdfTooLargeError, PdfInvalidFormatError, PdfTooManyPagesError, PdfParseError, PdfRenderError) is one defense layer alongside the version pin and CVE monitoring; no single layer is sufficient on its own.

Accepted risk

These mitigations reduce but do not eliminate the C-extension attack surface. Consumers SHOULD treat PDF inputs from outside this skill's PPTX-to-PDF pipeline as untrusted and apply additional sandboxing (subprocess, container) before feeding adversarial input.

Update policy

Re-check NVD and OSV advisories for MuPDF and PyMuPDF quarterly and on every pip-audit alert.

Cross-references

• microsoft/hve-core#1018 — original hardening request
• microsoft/hve-core#1020 — pip-audit CI for ongoing CVE monitoring (separate effort)

Troubleshooting

Environment Recovery

When scripts fail due to missing modules, import errors, or a corrupt virtual environment, recover with:

cd .github/skills/experimental/powerpoint
rm -rf .venv
uv sync

This recreates the virtual environment from scratch using pyproject.toml as the single source of truth. The Invoke-PptxPipeline.ps1 orchestrator runs uv sync automatically on each invocation unless -SkipVenvSetup is passed.

When uv itself is not available, install it first (see Installing uv above), then retry. When Python 3.11+ is not available, run uv python install 3.11 to have uv fetch and manage the interpreter.