---

Pick the right mode

For delivery-grade tasks, the default choice is Build Mode

If your PPT will be presented to clients, executives, investors, or in formal meetings, prefer Build Mode. It allows the LLM to plan the structure page by page, lock the visual direction, control layout precisely, and perform visual review and rework after the PPTX → PDF → PNG pipeline. It is the path with the highest visual control and delivery certainty among the three modes.

Mode	Best for	Layout control	Speed	Recommendation
Build Mode ⭐	Client delivery, proposals, strategy, pitch decks, editorial, formal reports	Highest: page-by-page, element-by-element control	Medium	First choice
FreeStyle Mode	Quick exploration, direction drafts, light PPTs with already-clarified content	Medium: auto-orchestrated by generate_ppt()	Fastest	Exploration first
VI Build Mode	PPTs with existing corporate templates, masters, or brand standards	Template-constrained: extract and preserve brand DNA	Medium	Template first

How to decide

• You care whether “the final result looks professional” rather than just needing a draft: Build Mode;
• You want to quickly validate a topic, content, or style direction: FreeStyle Mode;
• You must adhere to a corporate template, logo, fonts, and layout: VI Build Mode.

FreeStyle’s generate_ppt(query=...) and generate_ppt(content=...) are two input styles of the same mode, not two independent generation engines. Whichever mode you choose, formal delivery must go through the PNG visual check.

Core value: design quality

pptx-designer is responsible for turning design decisions into an editable PPTX; this Skill is responsible for the quality of the design decisions and the delivery process:

需求确认
  → 领域判断与页面结构
  → 视觉方向建议与用户确认
  → 设计 token / 页面锚点锁定
  → pptx-designer 生成可编辑 PPTX
  → PPTX → PDF → PNG
  → 第一门：整体视觉效果与客户级完成度
  → 第二门：严重缺陷、需求和可编辑性检查
  → 源码/内容返工并重新渲染
  → 用户确认与交付

"Running successfully" does not mean design complete. The Skill directly inspects exported PNGs to judge visual focus, density, hierarchy, composition, and whether it meets user needs. Only after passing two gates and completing rework does it enter user confirmation: Gate 1 checks overall visual effect and client-grade completeness; Gate 2 checks severe defects, requirement coverage, and editability.

Before generation, the LLM organizes user requirements into a traceable visual acceptance contract; after generating the PNGs, it checks each item against the requirements and page evidence, recording PASS, NEEDS_REVISION, or BLOCKED. So the PNG check is not a vague judgment of “does it look nice,” but a verification that the result truly meets the user’s goals.

Design case studies

Complete PowerPoint examples you can download, open, and keep editing. They cover technical systems, infrastructure research, scientific evidence, cultural architecture, and urban strategy, showing how this skill combines content structure, visual direction, and native editable objects into a full presentation.

Example	Design Positioning	Visual Language & Design Focus
AI Agent Operating System	Technical system blueprint	Dark grid, layered architecture, fluorescent accents, process & governance
AI Infrastructure Economics	Editorial industry research	Paper texture, physical constraint metaphors, data hierarchy, strategic narrative
Single-Cell CAR T Atlas	Paper-style scientific narrative	Figure-evidence structure, research design, evidence boundaries & editable mechanism diagrams
Louvre Abu Dhabi	Architectural cultural narrative	Real photography, editable geometry, climate logic & museum urban space
Vertical City Retrofit	Urban renewal strategy	Architectural sections, system diagrams, scenario data, governance & decision framework
COUTURE COLOR — Objects of Desire	Couture beauty editorial narrative	Full-screen makeup portraits, makeup actions on the same model, editable product structure & material narrative

These examples are not meant to prove that the code runs, but to showcase the complete result from design judgment to final page completion. For more pages and download links, see the online example gallery and examples/README.md.

Click any preview to open the online viewer, browse the full pages, and download PPTX or PDF:

Install

Clone the repository first, then run the installer from the repository root. The installer automatically installs the published pptx-designer Python package and copies the skill bundle to the selected coding assistant:

# Clone the skill repository
git clone https://github.com/sunchaokun/PPT-Design-Skill.git
cd PPT-Design-Skill

python installer/install.py --platform opencode --force
python skill/scripts/check_runtime.py

Use installer/install.py to complete the Skill installation. The install.py in the repository root is only for installing the Python runtime package pptx-designer and does not register the Skill in your coding tool.

Replace opencode with claude, codex, deepseek-harness, or all as needed. Restart the coding assistant after installation.

Why is LibreOffice an optional dependency?

PPTX generation itself only depends on the Python package pptx-designer and does not require LibreOffice. However, according to the Skill's quality process, after generating the PPTX, it must also be rendered to PDF and PNG for checking text overflow, image cropping, composition, and page-to-page rhythm:

• When Microsoft PowerPoint is available, Windows prioritizes PowerPoint COM rendering;
• When PowerPoint is not available, LibreOffice's soffice is used to convert PPTX to PDF;
• Poppler's pdftoppm is then used to convert the PDF to PNG.

Therefore, LibreOffice is a rendering fallback for environments without PowerPoint, not a PPTX generator, and not a dependency that every user must install. Run the commands below to check the current environment:

python skill/scripts/check_runtime.py

The installer checks PATH, the default Windows install directory, and the registry for LibreOffice, so it will not falsely report it as missing just because soffice.exe is not on PATH. Desktop software will not be silently installed; if you need to explicitly install LibreOffice and Poppler with winget, you can run:

On Windows, users who explicitly want the installer to use winget may run:

python installer/install.py --platform opencode --force --render-deps

Inspecting Real Examples

python skill/scripts/inspect_pptx.py examples/new_examplex/louvre_abudhabi/output/louvre_abudhabi_complete.pptx --pretty
powershell -ExecutionPolicy Bypass -File skill/scripts/render_pptx.ps1 `
  -InFile examples/new_examplex/louvre_abudhabi/output/louvre_abudhabi_complete.pptx `
  -OutDir output/louvre-abudhabi-rendered

Repeat this for other maintained examples. After export, the LLM must inspect the PNGs directly — checking composition, hierarchy, readability, cropping, page rhythm, and editability. Fix and re-render on any issue.

Documentation

• Skill Main Flow
• Design Principles
• Public API
• Quality & Delivery
• Cross-platform Installation
• Real Evaluation Sample
• Couture Visual Direction Evaluation
• Scientific Research Results Report Evaluation

What Problem It Solves

Checking code, files, and structure alone cannot guarantee the PPT meets design requirements. Even when it "runs successfully," issues like weak hierarchy, crowded pages, bad cropping, unreadable charts, repetition, and inconsistent style may remain.

This skill treats the visual result as part of the deliverable:

1. The user first confirms requirements and audience;
2. The LLM first designs the page structure and visual direction;
3. pptx-designer turns the confirmed design decisions into an editable PPTX;
4. Pages are exported through the confirmed PPTX -> PDF -> PNG path;
5. The LLM directly inspects the PNGs, judging page by page whether the design requirements are met;
6. If issues are found, go back to the Python source code or content for revision;
7. Re-export and re-check, then hand off to the user for final confirmation.

Design

This skill adopts a mature Designer Mindset rather than reducing design to picking a style parameter:

Capability	Role
Audience-first	Determine page expression based on audience, context, and action goals
Narrative planning	Design page-level narrative before generating code
Domain paradigms	Scientific research, papers, technology, healthcare, government, and business use different paradigms
Design system	Lock in colors, fonts, spacing, grid, imagery, and component language
Density control	Control information density on pages, avoiding cramming with small font sizes
Structural variation	Page structure changes with communication goals instead of repeating the same card
Native editability	Text, shapes, charts, and supported SVG remain editable
PNG visual review	Directly inspect real exported images, not just source code

Modes

Mode	Use Cases	Core Implementation
Build Mode	Delivery-grade precise design on a blank canvas	Python + pptx_designer.tools.*
FreeStyle Mode	Quick exploration or goal-driven generation	generate_ppt(query=...) / generate_ppt(content=...)
VI Build Mode	Corporate templates and brand compliance	extract_design_context() + atomic Build + VIBuildDelivery

FreeStyle

FreeStyle uses pptx-designer.generate_ppt() to complete goal-driven generation within the library:

from pptx_designer import generate_ppt
from pptx_designer.renderer.theme import ThemeComposer

theme = ThemeComposer().compose(style="dark-tech", seed=17)
result = generate_ppt(
    "AI startup investor pitch",
    theme=theme,
    output="output/pitch.pptx",
)

When page goals and copy are already clear, use structured content:

result = generate_ppt(
    content={
        "title": "Q4 Revenue Review",
        "pages": [
            {"goal": "hook", "title": "Q4 2026", "subtitle": "Record quarter"},
            {"goal": "problem", "title": "The pressure is visible", "bullets": [
                "Enterprise demand is growing",
                "Delivery capacity is the constraint",
            ]},
            {"goal": "data", "title": "Key metrics", "bullets": [
                "Revenue: $12.8M",
                "Retention: 89%",
            ]},
        ],
    },
    theme=theme,
    output="output/review.pptx",
)

Both query and content belong to FreeStyle; they are not two different rendering engines. content simply gives the LLM clearer control over page goals and copy; use Build Mode when precise coordinates are needed. theme must be the full resolved theme returned by ThemeComposer.compose(); when passing it, do not also pass style, palette, fonts, decoration, layout, mood, or style_seed.

VI Build Mode

Use VI Build when the user provides a template.pptx, an enterprise master, or explicitly requests brand compliance:

1. Use extract_design_context() to extract deterministic visual evidence;
2. Manually confirm framework pages, writable text slots, fixed visual layers, and visual grammar;
3. Design content pages using content_model, atomic components, precise geometry, and relation_bindings;
4. Compile content pages with VITemplateAdapter.compile_atomic() and deliver them with VIBuildDelivery;
5. Check consistency between original and new pages via PPTX -> PDF -> PNG.

When overlaying brand, theme, or page context onto template evidence, use merge_vi_design_context(), not the generic merge_design_context().

VI Build cannot promise pixel-level replication of all PowerPoint masters, SmartArt, animations, and OOXML behaviors. See template-brand.md for detailed boundaries.

Build Mode

Build Mode is the delivery-grade path. The LLM generates plain Python files, and layout, copy, colors, and data can all be reviewed, modified, and rebuilt in Git:

from pptx_designer import Presentation
from pptx_designer.renderer.theme import ThemeComposer
from pptx_designer.tools.cards import kpi_card
from pptx_designer.tools.layout import page_header
from pptx_designer.tools.shapes import rect

theme = ThemeComposer().compose(style="professional", seed=17)
prs = Presentation(theme=theme, strict_theme=True)
slide = prs.slides.add_slide(prs.slide_layouts[6])
page_header(slide, "Q4 Revenue Report", "Financial Summary")
kpi_card(slide, 1.0, 2.0, 3.5, 1.5, "$12.8M", "Revenue", "+23%")
rect(slide, 0.5, 6.8, 12.3, 0.08, fill="primary")
prs.save("output/report.pptx")

Build Mode rules:

• Use inches for all coordinates;
• Use the pptx_designer public API;
• Prefer native text, shapes, charts, and diagrams;
• Use cover_image() to maintain image aspect ratio;
• Centralize colors in design tokens or the C dictionary;
• Do not use legacy ppt_pro_max or private modules;
• After generation, must run, reopen, export, and perform visual inspection.

Three Control Variables

Control Variable	Low	Medium	High
Variance	Uniform grid and components	Two to three page strategies	Section pages and multiple structures
Motion	Static or fade-in	Section transitions and emphasis	Stronger motion only when suitable for presentation scenarios
Density	Large whitespace, few elements	Mixed narrative and data	Dashboards, tables, and high-density information

These variables affect structure and rhythm, not just color. Scientific, academic, and medical contexts usually need less decoration and motion, even for tech themes.

Prohibited Behaviors

• Generating a full PPT without a defined requirement and structure;
• Calling proposals structurally different when only colors/fonts change;
• Repeating the same card or bullet layout on every page;
• Using small fonts to fit excessive unedited content;
• Fabricating metrics, cases, citations, or evidence;
• Stretching images or using unrelated images;
• Baking entire pages into screenshots instead of editable objects;
• Applying fundraising templates to scientific, paper, or medical content;
• Only confirming Python and PPTX success without viewing PNGs;
• Not regenerating or re-inspecting after PNG issues are found.

Running and Rendering

If you need to reinstall or upgrade the Python runtime, you can run the installer directly; it will handle pptx-designer automatically:

python installer/install.py --platform all --force
python skill/scripts/check_runtime.py

Install the skill into a coding tool:

python installer/install.py --platform claude --force
python installer/install.py --platform codex --force
python installer/install.py --platform opencode --force
python installer/install.py --platform deepseek-harness --force

Export PPTX, PDF, and PNG:

powershell -ExecutionPolicy Bypass -File skill/scripts/render_pptx.ps1 `
  -InFile examples/new_examplex/louvre_abudhabi/output/louvre_abudhabi_complete.pptx `
  -OutDir output/louvre-abudhabi-rendered

The renderer prefers Microsoft PowerPoint COM; when PowerPoint is unavailable, it uses LibreOffice to generate a PDF and then Poppler's pdftoppm to generate PNGs. Desktop renderers are system dependencies and can be explicitly installed:

python installer/install.py --render-deps

Delivery Checklist

Delivery usually includes:

• .pptx file;
• Rebuildable Python source code or structured content;
• .pdf preview file;
• PNG for each page or a contact sheet;
• Basic structural check results;
• PNG visual inspection results;
• User's final confirmation record.

Directory Layout

PPT-Design-Skill/
├── skill/
│   ├── SKILL.md
│   ├── agents/openai.yaml
│   ├── references/
│   └── scripts/
├── docs/
│   ├── README_EN.md
│   └── usage-guide.md
├── examples/new_examplex/
│   └── six maintained case-study packages
├── installer/
├── docs/
├── install.py
└── skill.json