Step-by-step execution and dependencies

Follow this Skill's workflow in order. Before a step uses a library, command-line tool, runtime, or font, check only the dependencies required by that step; do not assume they are installed.
Reuse dependencies that are available. If one is missing, install only that dependency using the current OS and an available package manager, then verify it and retry the original step. Do not install the entire dependency list in advance.
Use the active Python environment (python -m pip install <package>, or the matching python); create a task-local virtual environment if needed. Install Node.js libraries in the task project (npm install <package>) so the script can resolve them. For system tools and fonts, use the available OS package manager (for example, Homebrew on macOS, apt on Debian/Ubuntu, or winget on Windows).
Follow the host's permission flow when installation needs approval. If the package manager or required permission is unavailable, or installation/download fails, report the missing dependency and affected step; do not retry indefinitely or claim the step passed. Continue independent steps when possible.
Keep the original workflow and quality checks. Check fonts only when rendering requires them. Steps using only text, built-in tools, or self-contained HTML require no package installation; external tool access or authentication must be handled through the host, not a package manager.

Path and Runtime Conventions (Read Before Running Commands)

Python Command: This machine uses python (on Windows, python3 is usually not available). All commands below use python uniformly.
Script Path: Skill scripts are located in AppData/skills/pptx/scripts/ (relative to the project root). Script commands in the sections below and in editing.md / pptxgenjs.md are written as absolute relative paths from this base directory and can be run directly from the project root.
Working Directory: Commands assume the current working directory is the project root. If the working directory differs (e.g., default_workdir is changed to another directory), replace AppData/skills/pptx with the absolute path to the skill directory.
Node.js: Before running npm/node (required by pptxgenjs), add the Node.js directory to the PATH according to the project rules.

PPTX Skill

Quick Reference

Task	Guide
Read/analyze content	`python -m markitdown presentation.pptx`
Edit or create from template	Read editing.md — QA: `validate_layout.py` + `markitdown`
Create from scratch	1. Plan content → 2. Pre-generate assets → 3. Read pptxgenjs.md
Prevent overflow by design	Read pptxgenjs.md
Generate design system	`python AppData/skills/pptx/scripts/design/search.py "<topic>" --design-system`
Post-generation fix	`python AppData/skills/pptx/scripts/fix_pptx.py output.pptx`
Layout QA (critical first)	`python AppData/skills/pptx/scripts/validate_layout.py presentation.pptx`

Reading Content

# Text extraction
python -m markitdown presentation.pptx

# Raw XML
python AppData/skills/pptx/scripts/unpack.py presentation.pptx unpacked/

Editing Workflow

Read editing.md for full details.

Analyze template with markitdown
Unpack + style-layer check + Theme & Style alignment plan
Manipulate slides → edit content → clean → pack
⚠️ Layout QA (mandatory gate): python AppData/skills/pptx/scripts/validate_layout.py output.pptx --slides <edited_slide_numbers>
⚠️ Content QA (mandatory): python -m markitdown output.pptx

Creating from Scratch

Read pptxgenjs.md for full details.

Use when no template or reference presentation is available.

Required Slide Structure (From-Scratch Only)

When creating a presentation from scratch, you MUST follow this structure:

Slide 1: Cover page
Slide 2: Table of contents (agenda)
Slide 3 onward: Content sections in the exact order listed on Slide 2
Final slide: Closing/thank-you page

Do not skip the table of contents slide. Do not place content slides before the table of contents.

⚠️ No Blank Slides Allowed

Every slide MUST contain at least one visible element (addText, addShape, addImage, addChart, or addTable) inside the slide. A slide with only a background color and no content elements is a generation defect.

Common causes of blank slides:

Forgetting to add content to section divider / transition slides
Token truncation mid-generation leaving some slides empty
Assuming slide layout or master will auto-fill content (they won't — pptxgenjs creates minimal layouts with no inherited shapes)

If you intend a slide as a section divider, you MUST explicitly add elements — e.g., a large section number, title text, and/or decorative shapes.

⚠️ REQUIRED: Pre-Generation Planning

Before writing any code, you MUST complete these planning steps:

⚡ Quick Path for Simple Requests: When the user asks for a short/simple deck (≤ 6 pages, single topic, no complex diagrams), skip the formal planning output and go straight to Step 3 (write code) using the standard Cover + TOC + (N-3) Content + Closing structure. Quick path = no verbose plan in your response body, just build and run the script.

Step 1: Output Content Design Plan

Present a structured plan covering:

Overall Theme & Style
- Color palette choice (reference "Design Ideas" section)
- Typography pairing
- Visual motif to carry across slides

Slide-by-Slide Outline

Slide 1: Cover - Layout type, key elements
Slide 2: Table of contents - Ordered section list
Slide 3: [Section 1 from TOC] - Layout type, key elements, insight plan (if visual)
...
Slide N: Closing / Thank You - Layout type, key elements
...

Visual Elements Inventory
- List all images, icons, charts, and diagrams needed
- Mark each as: [Built-in] (pptxgenjs shapes/charts) or [External] (needs pre-generation)

Example planning output:

## Presentation Plan

**Theme:** Ocean Gradient palette (065A82, 1C7293, 21295C)
**Fonts:** Georgia (headings) + Calibri (body)
**Motif:** Rounded cards with left accent border

### Slides:
1. Cover Slide - Centered title, gradient background
2. Table of Contents - Overview / Architecture / Metrics / Timeline
3. [Section 1 from TOC] - Layout type, key elements, insight plan (if visual)
...
n. Thank You - Closing statement + contact

⚠️ After outputting your plan, IMMEDIATELY proceed to Step 2 and Step 3. Do NOT re-plan, do NOT restate the same outline with minor variations. Output the plan ONCE, then start writing pptxgenjs code.

Step 2: Pre-Generate External Assets

For figures marked [External], generate them BEFORE writing pptxgenjs code.

⚠️ CRITICAL: Color Consistency

All generated diagrams and charts MUST use the same color palette as the presentation. Define colors at the top of your generation script based on your chosen theme.

Option A: Native Shapes/Charts First (REQUIRED default)

ALL architecture diagrams, flowcharts, process diagrams, org charts, and relationship diagrams MUST be built with pptxgenjs native shapes (RECTANGLE, OVAL, LINE, connectors + addText). See pptxgenjs.md "Building Diagrams with Native Shapes" for patterns and examples.

Use a strong template slide (process, comparison, 2-column, icon grid) when it fits
Use pptxgenjs native shapes (boxes/arrows/lines + text) for flows, architectures, and hierarchies
Use pptxgenjs charts for simple data charts (bar, pie, line, etc.)

Only fall back to matplotlib for complex statistical charts (heatmaps, scatter plots, box plots) that pptxgenjs charts cannot handle. Only fall back to Mermaid when the diagram is too complex for native shapes AND involves many cross-links.

Option B: Matplotlib/Python Charts

Define color palette at the start to match your PPT theme:

import matplotlib.pyplot as plt
import matplotlib.colors as mcolors

# ============================================================
# COLOR PALETTE - Match your PPT theme
# ============================================================
# Example: "Ocean Gradient" theme
COLORS = {
    'primary': '#065A82',
    'secondary': '#1C7293',
    'accent': '#21295C',
    'background': '#F0F7FA',
    'text': '#21295C',
    'light': '#E8F4F8',
}

# Color cycle for multiple data series
COLOR_CYCLE = [COLORS['primary'], COLORS['secondary'], COLORS['accent'], '#4A90A4', '#2D5A6B']

# Apply theme globally
plt.rcParams.update({
    'axes.prop_cycle': plt.cycler(color=COLOR_CYCLE),
    'axes.facecolor': 'none',
    'axes.edgecolor': COLORS['text'],
    'axes.labelcolor': COLORS['text'],
    'text.color': COLORS['text'],
    'xtick.color': COLORS['text'],
    'ytick.color': COLORS['text'],
    'figure.facecolor': 'none',
    'font.family': 'sans-serif',
    'font.size': 12,
})
# ============================================================

# Create chart with theme colors
fig, ax = plt.subplots(figsize=(8, 5), dpi=150)
bars = ax.bar(['Q1', 'Q2', 'Q3', 'Q4'], [25, 40, 35, 50],
              color=[COLORS['primary'], COLORS['secondary'], COLORS['primary'], COLORS['secondary']],
              edgecolor=COLORS['accent'], linewidth=1.5)
ax.set_title('Quarterly Revenue', fontsize=16, fontweight='bold', color=COLORS['text'])
ax.set_ylabel('Revenue ($M)', color=COLORS['text'])
ax.spines['top'].set_visible(False)
ax.spines['right'].set_visible(False)

plt.tight_layout()
width_px, height_px = int(8 * 150), int(5 * 150)
plt.savefig(f'chart_{width_px}x{height_px}.png', dpi=150, transparent=True)
plt.close()

Matplotlib palette templates:

# Midnight Executive
COLORS = {'primary': '#1E2761', 'secondary': '#CADCFC', 'accent': '#FFFFFF', 'text': '#1E2761'}

# Forest & Moss
COLORS = {'primary': '#2C5F2D', 'secondary': '#97BC62', 'accent': '#F5F5F5', 'text': '#2C5F2D'}

# Coral Energy
COLORS = {'primary': '#F96167', 'secondary': '#F9E795', 'accent': '#2F3C7E', 'text': '#2F3C7E'}

# Warm Terracotta
COLORS = {'primary': '#B85042', 'secondary': '#E7E8D1', 'accent': '#A7BEAE', 'text': '#B85042'}

# Teal Trust
COLORS = {'primary': '#028090', 'secondary': '#00A896', 'accent': '#02C39A', 'text': '#028090'}

Use for:

Complex statistical charts (bar, line, pie, scatter, radar, etc.)
Custom visualizations not supported by pptxgenjs
Heatmaps, scatter plots, box plots

⚠️ Do NOT use matplotlib for:

Architecture diagrams
Flowcharts / process diagrams
Org charts / hierarchy diagrams
Network topology diagrams
Any diagram that primarily shows relationships between components

These MUST be built with pptxgenjs native shapes so they render as editable PPT objects — not raster images.

matplotlib - Charts with CJK Support

When creating charts/graphs with matplotlib that include Chinese text, you MUST configure the font:

import os
import platform
import matplotlib.pyplot as plt
import matplotlib

def setup_matplotlib_cjk():
    """Configure matplotlib to support CJK characters"""
    system = platform.system()

    if system == "Darwin":  # macOS
        font_names = ['Arial Unicode MS', 'PingFang SC', 'Heiti SC', 'STHeiti']
    elif system == "Windows":
        font_names = ['Microsoft YaHei', 'SimHei', 'SimSun']
    else:  # Linux
        font_names = ['Noto Sans CJK SC', 'WenQuanYi Zen Hei', 'Droid Sans Fallback']

    # Find available font
    available_fonts = [f.name for f in matplotlib.font_manager.fontManager.ttflist]
    for font_name in font_names:
        if font_name in available_fonts:
            plt.rcParams['font.sans-serif'] = [font_name] + plt.rcParams['font.sans-serif']
            plt.rcParams['axes.unicode_minus'] = False  # Fix minus sign display
            return font_name
    return None

# Setup CJK font before creating charts
cjk_font = setup_matplotlib_cjk()

# Create a bar chart with Chinese labels
categories = ['第一季度', '第二季度', '第三季度', '第四季度']
values = [120, 135, 142, 158]

plt.figure(figsize=(10, 6))
plt.bar(categories, values, color='steelblue')
plt.title('季度销售数据 Quarterly Sales', fontsize=16)
plt.xlabel('季度 Quarter', fontsize=12)
plt.ylabel('销售额 Sales', fontsize=12)
plt.tight_layout()
plt.savefig('chart.png', dpi=150)
plt.close()

Option C: Web Search for Images

Search for relevant images when:
- Stock photos or illustrations are needed
- Icons or logos are required
- Reference images for concepts

Option D: Mermaid Diagrams (Last Resort)

Use only when the diagram cannot be represented cleanly with native shapes/layout, and keep it consistent with the deck:

# Install if needed: npm install -g @mermaid-js/mermaid-cli

Create a theme config file matching your PPT palette:

// mermaid-config.json - Example for "Ocean Gradient" theme
{
  "theme": "base",
  "themeVariables": {
    "primaryColor": "#065A82",
    "primaryTextColor": "#FFFFFF",
    "primaryBorderColor": "#21295C",
    "secondaryColor": "#1C7293",
    "secondaryTextColor": "#FFFFFF",
    "secondaryBorderColor": "#065A82",
    "tertiaryColor": "#E8F4F8",
    "tertiaryTextColor": "#21295C",
    "lineColor": "#21295C",
    "textColor": "#21295C",
    "mainBkg": "#E8F4F8",
    "nodeBorder": "#065A82",
    "clusterBkg": "#F0F7FA",
    "titleColor": "#21295C",
    "edgeLabelBackground": "#FFFFFF"
  }
}

cat > diagram.mmd << 'EOF'
graph LR
    A[Client] --> B[API Gateway]
    B --> C[Service A]
    B --> D[Service B]
EOF

# Prefer high resolution export for PPT usage
mmdc -i diagram.mmd -o diagram.png -c mermaid-config.json -b white -w 1600 --scale 2

Step 3: Image Naming Convention (REQUIRED)

All generated images MUST include dimensions in the filename:

{name}_{width}x{height}.png

Examples:

architecture_800x600.png - 800px wide, 600px tall
timeline_1200x400.png - 1200px wide, 400px tall
chart_600x600.png - 600px square

When saving images, always include dimensions:

# Matplotlib example
fig, ax = plt.subplots(figsize=(8, 5), dpi=150)
# ... create chart ...
width_px = int(8 * 150)   # 1200
height_px = int(5 * 150)  # 750
plt.savefig(f'chart_{width_px}x{height_px}.png', dpi=150, transparent=True)

# Generic: save image with dimensions in filename

Post-Generation Fix & QA

Always run these after generation.

Layout Validation (Mandatory First Gate)

python AppData/skills/pptx/scripts/validate_layout.py presentation.pptx

Checks for:

Text overflow (text exceeding shape boundaries)
Missing slides or blank slides (no content elements)
Slide order issues
Slide dimensions consistency

Content QA (Mandatory Second Gate)

python -m markitdown presentation.pptx

Verify that:

All intended content is present
No corrupt or missing text
Images are referenced correctly

Post-Generation Fix Tool

python AppData/skills/pptx/scripts/fix_pptx.py output.pptx

Automatically fixes common issues:

Resizes shapes to fit text
Removes blank slides
Adjusts font sizes to prevent overflow

Design System Generator

Get curated color palettes and typography suggestions for any topic:

python AppData/skills/pptx/scripts/design/search.py "<topic>" --design-system

Example:

python AppData/skills/pptx/scripts/design/search.py "artificial intelligence" --design-system

Returns a JSON with:

Recommended color palette (primary, secondary, accent, background, text)
Font pairings
Visual motif ideas

Troubleshooting Common Issues

Issue	Solution
pptxgenjs throws `ReferenceError: require is not defined`	Run script with Node.js, not in browser
Colors render incorrectly	Verify color hex values are 6 characters and in quotes
Text overflow on slides	Use `fontSize: shrinkToFit` property or reduce text length
Images not showing	Verify file path is absolute or relative to working directory
python command not found	Use `python3` on some systems; check Python installation
npm packages not resolved	Ensure script is in a directory with `package.json` or use `--prefix`
Mermaid diagrams missing fonts	Install required fonts (e.g., `Noto Sans CJK SC` for Chinese)

Related Files

editing.md - Detailed guide for template-based editing
pptxgenjs.md - Comprehensive guide for creating presentations from scratch
AppData/skills/pptx/scripts/ - All helper scripts

This skill provides a complete pipeline for PowerPoint generation, editing, and quality assurance. Follow the workflow strictly to ensure consistent, high-quality results.

Windy-X211/pptx

What is pptx?

Ask in your favorite AI

Documentation