roman-ryzenadvanced/codex-desktop-windows/ppt

PPT creation, editing, and analysis

Quick Setup

bash "$SKILL_DIR/setup.sh"    # Interactive environment check + install

Routing: Academic / Paper-Based Presentations → Beamer

STOP — check this before doing any work.

If the request matches any trigger below, skip the PPTX workflow entirely.

Read [`beamer.md`](beamer.md) in this directory and follow its instructions.

Beamer output format: PDF-style slides only.

Routing decision rule: The trigger table above applies to all languages. For non-English requests, match by semantic meaning — mentally translate the user's intent into English and check against the triggers.

Important: In many languages (e.g., Chinese, Japanese, Korean), "PPT" is a generic colloquial word for "slides" or "presentation" — it does NOT indicate a preference for .pptx format. Only route to the PPTX workflow when the user explicitly requests .pptx format (e.g., "I need a .pptx file", "export as pptx") or the content is clearly non-academic (e.g., marketing, business, teaching children).

Overview

A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.

Reading and analyzing content

Text extraction

To read the text content of a presentation, convert it to markdown:

python -m markitdown path-to-file.pptx

Raw XML access

For comments, speaker notes, slide layouts, animations, design elements, or complex formatting, unpack the presentation and inspect its raw XML.

Unpacking a file

python ooxml/scripts/unpack.py <office_file> <output_dir>

Note: unpack.py is at skills/pptx/ooxml/scripts/unpack.py relative to the project root. If not found, run find . -name "unpack.py" to locate it.

Key file structures

Typography and color extraction

When emulating an existing design, extract typography and colors before starting:

1. Theme file — ppt/theme/theme1.xml: colors (<a:clrScheme>), fonts (<a:fontScheme>)
2. Slide content — ppt/slides/slide1.xml: actual font usage (<a:rPr>) and colors
3. Global search — grep for <a:solidFill>, <a:srgbClr>, and font references across all XML files

Creating a new PowerPoint presentation using a template

When the user upload a pptx file,and do not ask you to create a fully new pptx,you must create a presentation that follows an existing template's design, you'll need to duplicate and re-arrange template slides before then replacing placeholder content.

Workflow

1. Extract template text AND create visual thumbnail grid:

• Extract text: python -m markitdown template.pptx > template-content.md
• Read template-content.md: Read the entire file. NEVER set any range limits.
• Create thumbnail grids: python scripts/thumbnail.py template.pptx
• See Creating Thumbnail Grids section for details

1. Analyze template and save inventory to a file:

• Visual Analysis: Review thumbnail grid(s) to understand layouts and design patterns
• Create and save template-inventory.md containing:

```markdown # Template Inventory Analysis Total Slides: [count] IMPORTANT: Slides are 0-indexed (first slide = 0, last slide = count-1)

## [Category Name]

• Slide 0: [Layout code if available] - Description/purpose
• Slide 1: [Layout code] - Description/purpose

[... EVERY slide must be listed ...] ```

1. Create presentation outline based on template inventory:

• Choose layouts that match your content structure
• CRITICAL: Match layout structure to actual content:
• Single-column layouts: Use for unified narrative or single topic
• Two-column layouts: Use ONLY when you have exactly 2 distinct items
• Three-column layouts: Use ONLY when you have exactly 3 distinct items
• Image + text layouts: Use ONLY when you have actual images
• Count your actual content pieces BEFORE selecting layout
• Save outline.md with content AND template mapping

1. Duplicate, reorder, and delete slides using `rearrange.py`:

``bash python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52 ``

1. Extract ALL text using the `inventory.py` script:

``bash python scripts/inventory.py working.pptx text-inventory.json ` Read text-inventory.json` entirely. NEVER set range limits.

1. Generate replacement text and save to JSON file:

• Verify which shapes exist in inventory — only reference shapes that are present
• Add "paragraphs" field to shapes that need content
• ALL text shapes from inventory will be cleared unless you provide "paragraphs"
• Paragraphs with bullets are automatically left-aligned
• Do NOT include bullet symbols (bullet, -, *) in text — they're added automatically
• Save to replacement-text.json

CRITICAL — JSON generation rules (learned from practice):

• Always use `json.dump()` to write the file — never write raw JSON strings in Python code.

Raw strings may embed unescaped " characters (e.g. "三遥", "线上+线下") that silently break JSON parsing. json.dump(data, f, ensure_ascii=False, indent=2) handles all escaping automatically.

• Respect small box character limits — check width and font_size from inventory before

writing text for numeric/label shapes. A box of width ≤ 0.7" at font_size ≥ 16pt can hold roughly 3–4 characters max. Keep percentage values like "99.7%" to ≤ 4 chars, or shorten (e.g. "100%" instead of "99.96%").

• Match replacement length to original — for body text boxes, count characters in the

original inventory text. Replacements significantly longer than the original will overflow. When in doubt, err shorter rather than longer.

• Test incrementally — validate with a 5-slide subset before writing the full deck.

replace.py blocks on overflow errors; fix them slide-by-slide rather than all at once.

1. Apply replacements:

``bash python scripts/replace.py working.pptx replacement-text.json output.pptx ``

Creating a new PowerPoint presentation without a template

When creating a new PowerPoint presentation from scratch, use the Design System + Component workflow.

Step 0 — Scene Classification (MANDATORY)

Before ANY design work, classify the presentation into one of the five scenes below:

Step 1 — Select Theme (MANDATORY)

Read `themes.md` and select a theme based on scene and content tone.

Output: State your chosen theme name, your chosen accent variant (A/B/C), and the full color palette (primary-80, primary-90, primary-5, accent, etc.) before writing any code.

Accent variant selection: Each theme offers 3 accent colors (A = default, B, C). Choose the variant that best matches the content tone. You may also mix — e.g., use accent-A for most slides and accent-B for emphasis pages — but keep the primary palette constant.

Theme selection tips:

• Work report → Ocean or Graphite
• Proposal / pitch → Ocean, Sandstone, or Twilight
• Teaching / courseware → Forest or Ocean
• Thesis defense → read `beamer.md` (PDF output); if .pptx is explicitly required, use Graphite or Forest
• Tech keynote / product launch → Deep Mineral or Mono
• Cultural / lifestyle / brand → Warm Retro
• ESG / sustainability → Deep Forest or Forest
• Consumer / lifestyle / female audience → Coral
• Healthcare / wellness / eco → Mint
• SaaS / AI / onboarding → Azure
• Annual events / launches / high-energy → Ember
• General → any theme that fits the content

After selecting a theme, note its Image Keywords and Mask Color — you will need them in Step 5.5.

Step 2 — Read Design System (MANDATORY)

Read `design-system.md`. Understand the color system (mandatory) and creative principles (guidelines). The color scale is the only hard constraint — everything else (spacing, font sizes, layout) is flexible.

Step 3 — Read HTML-to-PPTX Guide (MANDATORY)

Read `html2pptx.md` completely from start to finish. NEVER set any range limits when reading this file.

Step 4 — Plan Slide Sequence

For each slide, decide:

1. Which component from `components.md` to use as a starting point (or design from scratch)
2. What content to fill in — be generous with content; fill the slide
3. How to remix the component — change spacing, font sizes, card styles, backgrounds, proportions to create variety

KEY PRINCIPLES:

• Read `components.md` for available starting points
• Also read `data-viz-components.md` for data visualization components
• Adjacent slides MUST look distinctly different — vary layout structure, background, card treatment
• Fill the slide: Avoid large empty areas. If content is sparse, use larger typography, more generous spacing, bigger visual elements, or add decorative elements to create visual richness
• Every content slide should have at least one non-text visual element (color block, stat number, chart, icon, accent bar, photo, shape)
• Alternate between high-density and low-density pages for rhythm
• Use data visualization components when content contains numbers, comparisons, percentages
• Tables are a great way to enrich content — use content-table* or content-chart-* from components.md whenever content involves structured data, feature comparisons, schedules, or multi-attribute lists