# PPTX

> Read, create, and edit PowerPoint PPTX/PPT presentations. Use when the user explicitly mentions "ppt" or "PPT" (e.g. "做个PPT", "make a ppt"). If the user only says "演示文稿" or "presentation" without mentioning PPT, route to html-deck instead. Covers: parsing, summarizing, extracting content, inspecting themes/layouts, creating new decks with PptxGenJS, and editing existing PPTX while preserving formatting.

- Skill: `tomjiu/pptx` (Agent Skill, multi-file: 13 files)
- Install (CLI): `npx skillmds@latest add tomjiu/pptx`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomjiu/pptx/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: tomjiu (https://skillmd.com/u/tomjiu)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/tomjiu/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

| Need | Workflow |
| --- | --- |
| Existing PPTX inspection, extraction, search, preview, or audit | Use the inspection commands below |
| 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.

```bash
# 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:

```javascript
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:

```text
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**:

```powershell
# 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.

| 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 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