feat(skills): add 6 PowerPoint skill enhancements (#1481)

# Pull Request

## Description

Adds 6 enhancements to the PowerPoint skill addressing the most common
pain points in multi-theme deck production: manual spacing validation,
hardcoded theme colors in content-extra.py, per-project theme generation
boilerplate, lack of pre-flight checks, no audio pipeline, and missing
SVG export.

### New Scripts (4)

| Script | Enhancement | Lines |
|---|---|---|
| `validate_geometry.py` | Structural validation for edge margins,
adjacent gaps, boundary overflow (including left/top), and title
clearance | ~530 |
| `generate_themes.py` | YAML-driven theme variant generation with
single-pass hex and RGBColor color remapping | ~270 |
| `embed_audio.py` | WAV audio embedding into PPTX slides with per-slide
file matching | ~220 |
| `export_svg.py` | PPTX-to-SVG export via LibreOffice PDF conversion
and PyMuPDF rendering | ~250 |

### Modified Files (4)

| File | Change |
|---|---|
| `build_deck.py` | `--dry-run` pre-flight validation, `--verbose` flag,
`configure_logging()`, per-slide theme color lookup via
`themes[].slides` |
| `Invoke-PptxPipeline.ps1` | Wired geometric validation as Step 2b in
the existing Validate action |
| `SKILL.md` | CLI docs for dry-run, theme generation, audio embedding,
SVG export; updated script architecture table |
| `pptx.instructions.md` | Validation pipeline intro references 3-step
pipeline; theme colors in content-extra.py section |

## Related Issue(s)

Closes #1482

## Type of Change

**Code & Documentation:**

* [x] New feature (non-breaking change adding functionality)
* [x] Documentation update

**AI Artifacts:**

* [x] Reviewed contribution with `prompt-builder` agent and addressed
all feedback (N/A — scripts and wrappers are the primary deliverables;
instructions and SKILL.md updates follow established patterns verified
by automated validation)
* [x] Copilot instructions (`.github/instructions/*.instructions.md`)
* [x] Copilot skill (`.github/skills/*/SKILL.md`)

**Other:**

* [x] Script/automation (`.ps1`, `.sh`, `.py`)

## Testing

- 4 new test files: `test_validate_geometry.py` (37 tests),
`test_generate_themes.py` (20 tests), `test_embed_audio.py` (18 tests),
`test_export_svg.py` (11 tests)
- Full suite: **757 tests pass, 89.26% coverage** (above 85% threshold)
- ruff check and ruff format clean on all files
- All 4 new Python scripts pass AST parsing validation
- Geometric validation integrates into existing Validate pipeline (exit
code 1 for warnings, 2 for errors)
- `--dry-run` validates YAML parsing, speaker notes, content-extra.py
AST, and image refs without building
- Single-pass color remapping in both `remap_hex_in_text` and
`remap_rgb_in_python` prevents chain remapping
- Per-slide theme color lookup uses `themes[].slides` list with
`themes[0]` fallback; shallow-copies style dict

## Sample Prompts

### User Request

> "Build my presentation from the content directory, but first validate
the geometry and generate theme variants for the blue and green
palettes."

### Execution Flow

1. Agent reads `SKILL.md` to discover available scripts and their CLI
flags.
2. Runs `python scripts/build_deck.py --content-dir content/ --style
content/global/style.yaml --dry-run` to pre-flight validate content
YAML, speaker notes, and image references.
3. Runs `python scripts/generate_themes.py --content-dir content/
--themes themes.yaml --output-dir ../` to produce themed content
directory copies with remapped colors.
4. Runs `python scripts/build_deck.py --content-dir content/ --style
content/global/style.yaml --output presentation.pptx` to build the deck.
5. Runs `python scripts/validate_geometry.py --input presentation.pptx
--report report.md` to check margins, gaps, and overflow.
6. Optionally runs `python scripts/embed_audio.py --input
presentation.pptx --audio-dir voice-over/` to embed narration audio.
7. Optionally runs `python scripts/export_svg.py --input
presentation.pptx --output-dir svg/` to export slides as SVG.

### Output Artifacts

* `presentation.pptx` — Built deck with themed colors applied.
* `content-blue/`, `content-green/` — Generated theme variant content
directories.
* `geometry-validation-report.md` — Markdown report of margin, gap, and
overflow findings.
* `geometry-validation-results.json` — Machine-readable validation
results.
* `voice-over/*.wav` → embedded into PPTX slides (when audio pipeline is
used).
* `svg/slide-001.svg`, `svg/slide-002.svg`, ... — Exported SVG images.

### Success Indicators

* `--dry-run` exits with code 0 and reports no errors.
* `validate_geometry.py` exits with code 0 (clean) or 1 (warnings only,
no errors).
* Theme variant directories contain remapped hex colors in YAML and
`RGBColor()` calls in Python.
* Embedded audio plays automatically in PowerPoint's video export
workflow.
* SVG files render correctly when opened in a browser.

## Checklist

### Required Checks

* [x] Documentation is updated (if applicable)
* [x] Files follow existing naming conventions
* [x] Changes are backwards compatible (if applicable)
* [x] Tests added for new functionality (if applicable)

### AI Artifact Contributions

* [x] Used `/prompt-analyze` to review contribution (N/A — instructions
and SKILL.md updates are additive documentation of new CLI scripts;
patterns match existing validated sections)
* [x] Addressed all feedback from `prompt-builder` review (N/A — see
above)
* [x] Verified contribution follows common standards and type-specific
requirements

### Required Automated Checks

* [x] Markdown linting: `npm run lint:md`
* [x] Spell checking: `npm run spell-check`
* [x] Frontmatter validation: `npm run lint:frontmatter`
* [x] Skill structure validation: `npm run validate:skills`
* [x] Link validation: `npm run lint:md-links`
* [x] PowerShell analysis: `npm run lint:ps`
* [x] Plugin freshness: `npm run plugin:generate`
* [x] Docusaurus tests: `npm run docs:test`

## Security Considerations

* [x] This PR does not contain any sensitive or NDA information
* [x] Any new dependencies have been reviewed for security issues
* [x] Security-related scripts follow the principle of least privilege

## Additional Notes

Enhancement priority ranking derived from pain points during multi-theme
deck production:

| # | Enhancement | Priority |
|---|---|---|
| 4 | Structural/geometric validation | High |
| 5 | Color palette in content-extra.py style dict | High |
| 2 | Theme variant generation action | Medium |
| 6 | `--dry-run` pre-flight check | Medium |
| 3 | Audio embedding action | Medium |
| 1 | SVG export pipeline | Low |

---------

Co-authored-by: auyidi <auyidi@microsoft.com>

Author: auyidi1

.github/instructions/experimental/pptx.instructions.md

@@ -79,7 +79,9 @@ For partial rebuild workflows (update a few slides in an existing deck):
 
 ## Validation Criteria
 
-These criteria define the quality standards agents verify after building or updating slides. Visual checks use `validate_slides.py` and PPTX-only checks use `validate_deck.py`.
+These criteria define the quality standards agents verify after building or updating slides. The Validate pipeline runs three checks in sequence: PPTX property validation (`validate_deck.py`), geometric validation (`validate_geometry.py`), and optionally vision-based validation (`validate_slides.py`).
+
+Geometric validation runs automatically during the Validate action and checks the element positioning rules below programmatically. It catches margin violations, boundary overflow, and insufficient gaps without requiring vision model access.
 
 ### Element Positioning
 
@@ -116,6 +118,10 @@ These criteria define the quality standards agents verify after building or upda
 
 Use `#RRGGBB` hex values or `@theme_name` references for all colors. See the Color Syntax section in `content-yaml-template.md` for the full specification including theme brightness adjustments and dict syntax.
 
+### Theme Colors in content-extra.py
+
+When `style.yaml` defines a `themes` section, the build script populates `style[\"colors\"]` with the color map for the theme assigned to each slide via `themes[].slides`. Slides not explicitly assigned fall back to the first theme in the list. Use `style.get(\"colors\", {}).get(\"accent_blue\", \"#0078D4\")` in `content-extra.py` to reference theme-aware colors. This enables theme portability. The same script produces correct colors across all theme variants without regex replacement.
+
 ## Contextual Styling
 
 Slide decks often contain multiple visual themes (title slides, content slides, section dividers, dark vs. light themes). Rather than enforcing a single global style, derive colors, fonts, and layout patterns from context:

.github/skills/experimental/powerpoint/SKILL.md

@@ -404,6 +404,70 @@ python scripts/render_pdf_images.py \
 
 **Dependencies**: Requires LibreOffice for PPTX-to-PDF conversion and either `pdftoppm` (from `poppler`) or `pymupdf` (pip) for PDF-to-JPG rendering.
 
+### Dry-Run Validation
+
+```bash
+python scripts/build_deck.py \
+  --content-dir content/ \
+  --style content/global/style.yaml \
+  --dry-run
+```
+
+Validates content files without producing a PPTX. Parses all `content.yaml` files, checks for speaker notes, runs AST validation on `content-extra.py` scripts, and counts image assets. Exit codes:
+
+* code 0: no errors found
+* code 1: one or more slide-level content errors (YAML parse failures, invalid scripts)
+* code 2: configuration error (e.g., no slide content found in the content directory)
+
+### Generate Theme Variants
+
+```bash
+python scripts/generate_themes.py \
+  --content-dir content/ \
+  --themes themes.yaml \
+  --output-dir ../
+```
+
+Generates themed content directories from a base content directory using a color mapping YAML file. The themes YAML defines color replacement tables:
+
+```yaml
+themes:
+  fluent:
+    label: "Microsoft Fluent"
+    colors:
+      "#1B1B1F": "#FFFFFF"
+      "#F8F8FC": "#242424"
+```
+
+Each theme gets its own output directory with remapped `content.yaml`, `style.yaml`, and `content-extra.py` files. Images are copied as-is. Run `build_deck.py` on each themed directory to produce the PPTX.
+
+### Embed Audio
+
+```bash
+python scripts/embed_audio.py \
+  --input slide-deck/presentation.pptx \
+  --audio-dir voice-over/ \
+  --output slide-deck/presentation-narrated.pptx
+```
+
+Embeds WAV audio files into PPTX slides. Audio files are matched to slides by naming convention (`slide-001.wav`, `slide-002.wav`, etc.). The audio icon is placed off-screen (below the slide boundary) to keep it hidden during presentation. Pass `--slides` to embed audio on specific slides only.
+
+**Dependencies**: Requires `pillow` (`pip install pillow`) for poster frame generation.
+
+> [!NOTE]
+> WAV files are embedded uncompressed. For large narrated decks, consider pre-compressing audio before embedding to manage PPTX file size.
+
+### Export Slides to SVG
+
+```bash
+python scripts/export_svg.py \
+  --input slide-deck/presentation.pptx \
+  --output-dir slide-deck/svg/ \
+  --slides 3,5,10
+```
+
+Exports slides to SVG format via LibreOffice (PPTX → PDF) and PyMuPDF (PDF → SVG). Output files are named `slide-NNN.svg`. Pass `--slides` to export specific slides. **Dependencies**: Requires LibreOffice and `pymupdf`.
+
 ## Script Architecture
 
 The build and extraction scripts use shared modules in the `scripts/` directory:
@@ -419,8 +483,12 @@ The build and extraction scripts use shared modules in the `scripts/` directory:
 | `pptx_tables.py`       | Table element creation and extraction with cell merging, banding, and per-cell styling                                                                                                                 |
 | `pptx_charts.py`       | Chart element creation and extraction for 12 chart types (column, bar, line, pie, scatter, bubble, etc.)                                                                                               |
 | `validate_deck.py`     | PPTX-only validation for speaker notes and slide count                                                                                                                                                 |
+| `validate_geometry.py` | Structural validation for element edge margins, adjacent gaps, boundary overflow, and title clearance                                                                                                  |
 | `validate_slides.py`   | Vision-based slide issue detection and quality validation via Copilot SDK with built-in checks and plain-text per-slide output                                                                         |
 | `render_pdf_images.py` | PDF-to-JPG rendering via PyMuPDF with optional slide-number-based naming                                                                                                                               |
+| `generate_themes.py`   | Theme variant generation from a base content directory using a color mapping YAML file                                                                                                                 |
+| `embed_audio.py`       | WAV audio embedding into PPTX slides with per-slide file matching and off-screen audio icon placement                                                                                                  |
+| `export_svg.py`        | PPTX-to-SVG export via LibreOffice PDF conversion and PyMuPDF SVG rendering                                                                                                                           |
 
 ## python-pptx Constraints
 

.github/skills/experimental/powerpoint/pyproject.toml

@@ -5,6 +5,7 @@ requires-python = ">=3.11"
 dependencies = [
     "python-pptx",
     "pyyaml",
+    "ruamel.yaml",  # required by generate_themes.py for round-trip YAML fidelity
     "cairosvg",
     "Pillow",
     "pymupdf",

.github/skills/experimental/powerpoint/scripts/Invoke-EmbedAudio.ps1

@@ -0,0 +1,91 @@
+#!/usr/bin/env pwsh
+# Copyright (c) Microsoft Corporation.
+# SPDX-License-Identifier: MIT
+#Requires -Version 7.0
+
+<#
+.SYNOPSIS
+    Embed WAV audio files into a PowerPoint deck.
+
+.DESCRIPTION
+    Wrapper script that manages the Python virtual environment and invokes
+    embed_audio.py to embed per-slide WAV files into a PPTX presentation.
+
+.PARAMETER InputPath
+    Input PPTX file path.
+
+.PARAMETER AudioDir
+    Directory containing slide-NNN.wav files.
+
+.PARAMETER OutputPath
+    Output PPTX file path.
+
+.PARAMETER Slides
+    Comma-separated slide numbers to embed audio on (optional).
+
+.PARAMETER SkipVenvSetup
+    Skip virtual environment setup.
+
+.EXAMPLE
+    ./Invoke-EmbedAudio.ps1 -InputPath deck.pptx -AudioDir voice-over/ -OutputPath out.pptx
+
+.NOTES
+    Part of the powerpoint skill. Manages uv virtual environment setup
+    and delegates to embed_audio.py for WAV embedding into PPTX slides.
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)][ValidateNotNullOrEmpty()][string]$InputPath,
+    [Parameter(Mandatory = $true)][ValidateNotNullOrEmpty()][string]$AudioDir,
+    [Parameter(Mandatory = $true)][ValidateNotNullOrEmpty()][string]$OutputPath,
+    [Parameter(Mandatory = $false)][string]$Slides,
+    [Parameter(Mandatory = $false)][switch]$SkipVenvSetup
+)
+
+$ErrorActionPreference = 'Stop'
+
+#region Environment Setup
+
+$ScriptDir = $PSScriptRoot
+$SkillRoot = Split-Path -Parent $ScriptDir
+$VenvDir = Join-Path $SkillRoot '.venv'
+
+#endregion Environment Setup
+
+#region Main
+
+if ($MyInvocation.InvocationName -ne '.') {
+
+    try {
+        if (-not $SkipVenvSetup) {
+            if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
+                throw 'uv is required but was not found on PATH.'
+            }
+            uv sync --directory $SkillRoot
+        }
+
+        $python = if (Test-Path (Join-Path $VenvDir 'Scripts/python.exe')) {
+            Join-Path $VenvDir 'Scripts/python.exe'
+        } elseif (Test-Path (Join-Path $VenvDir 'bin/python')) {
+            Join-Path $VenvDir 'bin/python'
+        } else {
+            throw "Python interpreter not found in venv. Run: uv sync --directory `"$SkillRoot`""
+        }
+
+        $script = Join-Path $ScriptDir 'embed_audio.py'
+        $ScriptArgs = @($script, '--input', $InputPath, '--audio-dir', $AudioDir, '--output', $OutputPath)
+        if ($Slides) { $ScriptArgs += '--slides'; $ScriptArgs += $Slides }
+        if ($VerbosePreference -eq 'Continue') { $ScriptArgs += '-v' }
+
+        & $python @ScriptArgs
+        exit $LASTEXITCODE
+    }
+    catch {
+        Write-Error -ErrorAction Continue "Invoke-EmbedAudio failed: $($_.Exception.Message)"
+        exit 1
+    }
+
+}
+
+#endregion Main

.github/skills/experimental/powerpoint/scripts/Invoke-ExportSvg.ps1

@@ -0,0 +1,87 @@
+#!/usr/bin/env pwsh
+# Copyright (c) Microsoft Corporation.
+# SPDX-License-Identifier: MIT
+#Requires -Version 7.0
+
+<#
+.SYNOPSIS
+    Export PowerPoint slides to SVG images.
+
+.DESCRIPTION
+    Wrapper script that manages the Python virtual environment and invokes
+    export_svg.py to convert PPTX slides to SVG via LibreOffice and PyMuPDF.
+
+.PARAMETER InputPath
+    Input PPTX file path.
+
+.PARAMETER OutputDir
+    Output directory for SVG files.
+
+.PARAMETER Slides
+    Comma-separated slide numbers to export (optional).
+
+.PARAMETER SkipVenvSetup
+    Skip virtual environment setup.
+
+.EXAMPLE
+    ./Invoke-ExportSvg.ps1 -InputPath deck.pptx -OutputDir svg/
+
+.NOTES
+    Part of the powerpoint skill. Manages uv virtual environment setup
+    and delegates to export_svg.py for PPTX-to-SVG conversion.
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)][ValidateNotNullOrEmpty()][string]$InputPath,
+    [Parameter(Mandatory = $true)][ValidateNotNullOrEmpty()][string]$OutputDir,
+    [Parameter(Mandatory = $false)][string]$Slides,
+    [Parameter(Mandatory = $false)][switch]$SkipVenvSetup
+)
+
+$ErrorActionPreference = 'Stop'
+
+#region Environment Setup
+
+$ScriptDir = $PSScriptRoot
+$SkillRoot = Split-Path -Parent $ScriptDir
+$VenvDir = Join-Path $SkillRoot '.venv'
+
+#endregion Environment Setup
+
+#region Main
+
+if ($MyInvocation.InvocationName -ne '.') {
+
+    try {
+        if (-not $SkipVenvSetup) {
+            if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
+                throw 'uv is required but was not found on PATH.'
+            }
+            uv sync --directory $SkillRoot
+        }
+
+        $python = if (Test-Path (Join-Path $VenvDir 'Scripts/python.exe')) {
+            Join-Path $VenvDir 'Scripts/python.exe'
+        } elseif (Test-Path (Join-Path $VenvDir 'bin/python')) {
+            Join-Path $VenvDir 'bin/python'
+        } else {
+            throw "Python interpreter not found in venv. Run: uv sync --directory `"$SkillRoot`""
+        }
+
+        $script = Join-Path $ScriptDir 'export_svg.py'
+        $ScriptArgs = @($script, '--input', $InputPath, '--output-dir', $OutputDir)
+        if ($Slides) { $ScriptArgs += '--slides'; $ScriptArgs += $Slides }
+        if ($VerbosePreference -eq 'Continue') { $ScriptArgs += '-v' }
+
+        & $python @ScriptArgs
+        exit $LASTEXITCODE
+    }
+    catch {
+        Write-Error -ErrorAction Continue "Invoke-ExportSvg failed: $($_.Exception.Message)"
+        exit 1
+    }
+
+}
+
+#endregion Main

.github/skills/experimental/powerpoint/scripts/Invoke-GenerateThemes.ps1

@@ -0,0 +1,86 @@
+#!/usr/bin/env pwsh
+# Copyright (c) Microsoft Corporation.
+# SPDX-License-Identifier: MIT
+#Requires -Version 7.0
+
+<#
+.SYNOPSIS
+    Generate themed content directory variants from a base deck.
+
+.DESCRIPTION
+    Wrapper script that manages the Python virtual environment and invokes
+    generate_themes.py to produce themed content copies with remapped colors.
+
+.PARAMETER ContentDir
+    Path to the base theme's content directory.
+
+.PARAMETER ThemesPath
+    Path to a YAML file defining theme color mappings.
+
+.PARAMETER OutputDir
+    Parent directory where themed content directories are created.
+
+.PARAMETER SkipVenvSetup
+    Skip virtual environment setup.
+
+.EXAMPLE
+    ./Invoke-GenerateThemes.ps1 -ContentDir content/ -ThemesPath themes.yaml -OutputDir ../
+
+.NOTES
+    Part of the powerpoint skill. Manages uv virtual environment setup
+    and delegates to generate_themes.py for themed content generation.
+#>
+
+[CmdletBinding()]
+param(
+    [Parameter(Mandatory = $true)][ValidateNotNullOrEmpty()][string]$ContentDir,
+    [Parameter(Mandatory = $true)][ValidateNotNullOrEmpty()][string]$ThemesPath,
+    [Parameter(Mandatory = $true)][ValidateNotNullOrEmpty()][string]$OutputDir,
+    [Parameter(Mandatory = $false)][switch]$SkipVenvSetup
+)
+
+$ErrorActionPreference = 'Stop'
+
+#region Environment Setup
+
+$ScriptDir = $PSScriptRoot
+$SkillRoot = Split-Path -Parent $ScriptDir
+$VenvDir = Join-Path $SkillRoot '.venv'
+
+#endregion Environment Setup
+
+#region Main
+
+if ($MyInvocation.InvocationName -ne '.') {
+
+    try {
+        if (-not $SkipVenvSetup) {
+            if (-not (Get-Command uv -ErrorAction SilentlyContinue)) {
+                throw 'uv is required but was not found on PATH.'
+            }
+            uv sync --directory $SkillRoot
+        }
+
+        $python = if (Test-Path (Join-Path $VenvDir 'Scripts/python.exe')) {
+            Join-Path $VenvDir 'Scripts/python.exe'
+        } elseif (Test-Path (Join-Path $VenvDir 'bin/python')) {
+            Join-Path $VenvDir 'bin/python'
+        } else {
+            throw "Python interpreter not found in venv. Run: uv sync --directory `"$SkillRoot`""
+        }
+
+        $script = Join-Path $ScriptDir 'generate_themes.py'
+        $ScriptArgs = @($script, '--content-dir', $ContentDir, '--themes', $ThemesPath, '--output-dir', $OutputDir)
+        if ($VerbosePreference -eq 'Continue') { $ScriptArgs += '-v' }
+
+        & $python @ScriptArgs
+        exit $LASTEXITCODE
+    }
+    catch {
+        Write-Error -ErrorAction Continue "Invoke-GenerateThemes failed: $($_.Exception.Message)"
+        exit 1
+    }
+
+}
+
+#endregion Main