PPTX

Scope

Use this skill for PowerPoint .pptx work.

• Read slide text, tables, speaker notes, or comments
• Search existing deck content
• Extract embedded images
• Render slide screenshots
• Audit theme, layout, font, color, hyperlink, embedded object, and security metadata
• Create a new deck from scratch with PptxGenJS
• Imitate an existing deck's visual style with new content
• Edit an existing PPTX or template while preserving layout

Replace <skill_dir> with the actual skill path shown by the loader.

Router

If the request says "edit" but no source deck is available, assume from-scratch generation and state that assumption.

Inspection Commands

Default to uv run --with python-pptx for all Python workflows except comments, which has no extra dependency.

# Text, tables, notes, search
uv run --with python-pptx <skill_dir>/scripts/extract_pptx.py file.pptx

# Embedded images
uv run --with python-pptx <skill_dir>/scripts/extract_images.py file.pptx

# Review comments
uv run <skill_dir>/scripts/extract_comments.py file.pptx

# Format / metadata audit
uv run --with python-pptx <skill_dir>/scripts/audit_pptx.py file.pptx

# Screenshots (macOS only)
bash <skill_dir>/scripts/pptx-screenshot.sh file.pptx

High-value inspection flags:

• Slide subset: --slides 1,3,5 or --range 2-4
• Text filtering: --search "term", --regex, --ignore-case
• Speaker notes: extract_pptx.py --notes
• Image dry run: extract_images.py --list-only
• Comment output: extract_comments.py --format json
• Audit scope: audit_pptx.py --sections metadata,themes,...
• Screenshot subset: pptx-screenshot.sh --pages "1,3,5" --outdir ./previews

audit_pptx.py supports these sections:

• metadata: document properties
• masters: slide masters, layouts, usage counts
• themes: theme colors and font schemes
• shapes: per-slide shape inventory with position and text preview
• hyperlinks: URLs, actions, tooltips
• embedded: embedded files and OLE objects
• security: MSIP labels and custom XML parts

Use --format text only for human inspection. Prefer JSON when downstream processing is likely.

Generation Defaults

Use these defaults unless the user specifies otherwise and no template PPTX is provided for imitation:

• audience: business / professional
• tone: clear, restrained, presentation-ready
• layout: LAYOUT_16x9
• Chinese font: Microsoft YaHei
• English font: Arial unless a better option is justified
• palette and typography: choose from references/design-system.md
• page numbers: required on all non-cover slides

When a template PPTX is provided for imitation, the template's actual colors and fonts override these defaults.

Hard Constraints

These are mandatory unless the user explicitly overrides them:

1. Use LAYOUT_16x9.
2. Canvas boundary rule: LAYOUT_16x9 is 10" wide x 5.625" tall. Every element must satisfy x + w <= 10.0 and y + h <= 5.625. Coordinates that exceed these bounds will be clipped or overflow the slide edge. Do NOT assume the canvas is 13.3" wide — that is LAYOUT_WIDE, a different layout.
3. Create one file per slide: slides/slide-01.js, slides/slide-02.js, ...
4. Each slide file must export synchronous createSlide(pres, theme).
5. Never use async / await in createSlide().
6. Theme keys must be exactly primary, secondary, accent, light, bg.
7. Colors must be 6-character hex strings without #.
8. Do not encode opacity into hex strings.
9. All non-cover slides must include a page number badge near x 9.3, y 5.1.
10. Chinese text should use Microsoft YaHei.
11. No gradients or animation-style gimmicks.
12. Do not reuse mutable PptxGenJS option objects across calls.
13. Output filename must be descriptive; never use presentation.pptx.
14. Run QA before returning the deck — this is a blocking gate, not optional. Do NOT return the deck to the user until QA is complete. See references/pitfalls.md for the QA process.
15. When imitating a template, use the template's actual fonts. Only fall back to references/design-system.md font pairings when no template is provided.

From-Scratch Workflow

Use this when no source PPTX must be preserved.

1. Derive a concise outline from topic, audience, purpose, and expected depth.
2. Pick one palette, font pairing, and style recipe from references/design-system.md.
3. Assign each slide one page type from references/slide-types.md.
4. Create slides/slide-XX.js modules and keep layout variety where the outline calls for it.
5. Run the pre-compile lint in references/pitfalls.md#pre-compile-lint before compiling.
6. Create slides/compile.js, load slide modules in final order, and write slides/output/<descriptive-name>.pptx.
7. Run the QA process in references/pitfalls.md#qa-process, fix issues, and re-verify.

Minimal compile shape:

const pptxgen = require('pptxgenjs');
const pres = new pptxgen();
pres.layout = 'LAYOUT_16x9';

const theme = {
  primary: '22223b',
  secondary: '4a4e69',
  accent: '9a8c98',
  light: 'c9ada7',
  bg: 'f2e9e4'
};

require('./slide-01.js').createSlide(pres, theme);
pres.writeFile({ fileName: './output/my-deck-name.pptx' });

Template Imitation Workflow

Use this when the user provides a reference PPTX for visual style, but all content is new.

Step 1: Analyze Template Visual Identity

1. Take screenshots of 3-5 representative slides: cover, a content-heavy slide, and a data slide.
2. Run audit_pptx.py --sections themes,masters,shapes to extract theme colors, fonts, and layout usage.
3. Determine dark-mode vs light-mode:
   • Check the most-used slide layouts. If their backgrounds use dk1/dk2 colors with dark values such as 1A1A1A or 0D0D0D, the template is dark-mode.
   • Look at screenshots: dark backgrounds with light text indicate dark-mode.
4. Record the template's visual identity:
   • Slide background color
   • Primary text color
   • Accent color(s)
   • Card/panel background color
   • Font families for title and body

Step 2: Map to Theme Keys Faithfully

Map the template's actual colors to the 5-key theme, respecting the template's color roles:

bg        = actual slide background color (may be dark)
primary   = actual body text color (may be light)
accent    = primary accent/highlight color
secondary = secondary/muted text color
light     = card/panel background color

Do not pick from references/design-system.md palettes. Use the template's actual colors.

Do not assume bg is light and primary is dark. Dark-mode templates flip this.

Step 3: Use Template Fonts

Use the font families from the template audit, not references/design-system.md recommendations. Only fall back to recommended pairings if the template fonts are unavailable on the target system.

Step 4: Generate

Do all of the following (these are the From-Scratch Workflow steps, adapted — do NOT skip any):

1. Derive a concise outline from topic, audience, purpose, and expected depth.
2. Assign each slide one page type from references/slide-types.md.
3. Create slides/slide-XX.js modules and keep layout variety where the outline calls for it.
4. Run the pre-compile lint in references/pitfalls.md#pre-compile-lint before compiling.
5. Create slides/compile.js, load slide modules in final order, and write slides/output/<descriptive-name>.pptx.
6. Run the QA process in references/pitfalls.md#qa-process, fix issues, and re-verify. Do NOT return the deck until QA passes.

Skip palette/font selection (step 2 of From-Scratch) because palette and fonts come from the template.

Template Editing Workflow

Use this when the user provides a source PPTX and expects structure or layout to survive.

• Prefer preserving slide masters, theme relationships, and layout semantics.
• Complete structural edits first, then content edits.
• Follow references/editing.md for XML-level workflow and pitfalls.
• Only switch to from-scratch generation if it does not violate the user's intent.

Delivery Checklist

• slides render without runtime errors
• layout is LAYOUT_16x9
• no # in colors
• all slide modules are synchronous
• all non-cover slides include page numbers
• no placeholder/demo text remains
• titles do not wrap awkwardly
• repeated elements align consistently
• final file is written successfully
• inspection/editing tasks preserve the source file unless explicitly replacing it
• template imitation background color matches the template's dark/light mode
• template imitation fonts match the template's font families

Operational Notes

• Screenshots are macOS-only and require soffice plus swiftc.
• extract_comments.py supports classic comments only, not modern Office 365 collaborative comments.
• If targeted python-pptx editing is needed, read references/python-pptx-recipes.md on demand instead of keeping those patterns in main context.

Windows (win32) platform notes

On Windows, invoke bash scripts and piped commands via Git Bash:

# QA verification with markitdown
bash -c "python -m markitdown output.pptx | grep -iE 'xxxx|lorem|ipsum|placeholder'"

# Python inspection via uv
uv run --with python-pptx scripts/extract_pptx.py file.pptx

Note: scripts/pptx-screenshot.sh is macOS-only (requires Swift compiler + soffice). On Windows, use LibreOffice GUI export or python-pptx + pillow for slide previews.

If Git Bash or any tool is missing, read the mavis skill's references/windows-tool-bootstrap.md for detection + auto-install commands.

References

Mandatory for Generation Tasks

Read these before writing any slide code. Do not skip them even if you think you already know the API:

• references/pitfalls.md: pre-compile lint, QA process, common PptxGenJS failures — must run lint and QA
• references/pptxgenjs.md: PptxGenJS API, layout dimensions, text/shape/table options — must verify canvas dimensions
• references/slide-types.md: page type classification and layout patterns — must assign a type to each slide

Load On Demand

• references/design-system.md: palette, typography, style recipes (skip when imitating a template)
• references/editing.md: template-preserving editing workflow
• references/python-pptx-recipes.md: targeted python-pptx inspection or editing patterns