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
| Need | Workflow |
|---|---|
| Existing PPTX inspection, extraction, search, preview, or audit | Use the inspection commands below |
PPTX preview selection edit context (mavis.ppt_artifact_edit_request.v1) |
Read references/preview-selection-writeback.md; use the targeted workflow there, not the template-wide editing workflow |
| Existing PPTX provided and layout/style must be preserved | Follow references/editing.md |
| Reference PPTX provided for style imitation, but content is new | Run the Template Imitation Workflow |
| No source deck, or a fresh deck is acceptable | Run the From-Scratch Workflow |
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,5or--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 propertiesmasters: slide masters, layouts, usage countsthemes: theme colors and font schemesshapes: per-slide shape inventory with position and text previewhyperlinks: URLs, actions, tooltipsembedded: embedded files and OLE objectssecurity: 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:
Arialunless 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.
Editable Sidecar Metadata
When creating a new PPTX from scratch for Mavis, also write an optional sidecar element map:
slides/output/<descriptive-name>.mavis-ppt-map.json
This sidecar is editing metadata only. It must not replace the standard .pptx output, change
visible slide layout, or change the createSlide(pres, theme) slide-module contract. Use
references/element-map.md and scripts/mavis-ppt-map.cjs to record stable elementId, role,
text, style, and rectIn / normalizedRect coordinates for meaningful editable elements.
If the sidecar is unavailable for a deck, the PPTX is still valid and should be delivered after the normal QA process. Future artifact-edit flows can then fall back to preview text, screenshots, and coordinates as locator evidence.
Hard Constraints
These are mandatory unless the user explicitly overrides them:
- Use
LAYOUT_16x9. - Canvas boundary rule:
LAYOUT_16x9is 10" wide x 5.625" tall. Every element must satisfyx + w <= 10.0andy + 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 isLAYOUT_WIDE, a different layout. - Create one file per slide:
slides/slide-01.js,slides/slide-02.js, ... - Each slide file must export synchronous
createSlide(pres, theme). - Never use
async/awaitincreateSlide(). - Theme keys must be exactly
primary,secondary,accent,light,bg. - Colors must be 6-character hex strings without
#. - Do not encode opacity into hex strings.
- All non-cover slides must include a page number badge near x
9.3, y5.1. - Chinese text should use
Microsoft YaHei. - No gradients or animation-style gimmicks.
- Do not reuse mutable PptxGenJS option objects across calls.
- Output filename must be descriptive; never use
presentation.pptx. - 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.mdfor the QA process. - When imitating a template, use the template's actual fonts. Only fall back to
references/design-system.mdfont pairings when no template is provided.
From-Scratch Workflow
Use this when no source PPTX must be preserved.
- Derive a concise outline from topic, audience, purpose, and expected depth.
- Pick one palette, font pairing, and style recipe from
references/design-system.md. - Assign each slide one page type from
references/slide-types.md. - Create
slides/slide-XX.jsmodules and keep layout variety where the outline calls for it. - Run the pre-compile lint in
references/pitfalls.md#pre-compile-lintbefore compiling. - Create
slides/compile.js, load slide modules in final order, and writeslides/output/<descriptive-name>.pptx. - For Mavis-generated decks, write
slides/output/<descriptive-name>.mavis-ppt-map.jsonas a sidecar usingreferences/element-map.md. - 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
- Take screenshots of 3-5 representative slides: cover, a content-heavy slide, and a data slide.
- Run
audit_pptx.py --sections themes,masters,shapesto extract theme colors, fonts, and layout usage. - Determine dark-mode vs light-mode:
- Check the most-used slide layouts. If their backgrounds use
dk1/dk2colors with dark values such as1A1A1Aor0D0D0D, the template is dark-mode. - Look at screenshots: dark backgrounds with light text indicate dark-mode.
- Check the most-used slide layouts. If their backgrounds use
- 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):
- Derive a concise outline from topic, audience, purpose, and expected depth.
- Assign each slide one page type from
references/slide-types.md. - Create
slides/slide-XX.jsmodules and keep layout variety where the outline calls for it. - Run the pre-compile lint in
references/pitfalls.md#pre-compile-lintbefore compiling. - Create
slides/compile.js, load slide modules in final order, and writeslides/output/<descriptive-name>.pptx. - For Mavis-generated decks, write
slides/output/<descriptive-name>.mavis-ppt-map.jsonas a sidecar usingreferences/element-map.md. - 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.mdfor 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
- generated decks include an element-map sidecar when available, without changing the
.pptxoutput contract - 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
sofficeplusswiftc. extract_comments.pysupports classic comments only, not modern Office 365 collaborative comments.- If targeted
python-pptxediting is needed, readreferences/python-pptx-recipes.mdon 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.shis macOS-only (requires Swift compiler + soffice). On Windows, use LibreOffice GUI export orpython-pptx+ pillow for slide previews.
| Unix reference | Windows handling |
|---|---|
python3 / python -m |
python — works in both PowerShell and Git Bash |
/tmp/ for temp writes |
Git Bash maps /tmp/ automatically |
soffice |
Must be on PATH — winget install TheDocumentFoundation.LibreOffice |
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 QAreferences/pptxgenjs.md: PptxGenJS API, layout dimensions, text/shape/table options — must verify canvas dimensionsreferences/slide-types.md: page type classification and layout patterns — must assign a type to each slidereferences/element-map.md: optional sidecar metadata for Mavis-generated decks — must not replace the PPTX output contract
Load On Demand
references/design-system.md: palette, typography, style recipes (skip when imitating a template)references/editing.md: template-preserving editing workflowreferences/python-pptx-recipes.md: targeted python-pptx inspection or editing patterns