Core Philosophy
Simulate the complete workflow of a professional PPT design company (the level of tens of thousands of yuan per page), rather than "take an outline and apply a template":
- Research first, then generate -- Fill content with real data, do not fabricate out of thin air
- Separate planning from design -- Validate the information structure first, then do the visual packaging
- Content-driven layout -- Bento Grid card-style layout, each page's layout is determined by its content
- Consistent global style -- Define the style first, then generate page by page, ensuring cross-page consistency
- Intelligent image matching -- Use image generation capabilities to provide illustrations for each page (most environments have this capability)
Environment Awareness
Before starting work, self-assess the tool capabilities the agent has:
| Capability | Fallback Strategy |
|---|---|
| Information acquisition(search/URL/document/knowledge base) | All missing -> rely on materials provided by the user |
| Image generation(most environments have this) | Missing -> replace with pure CSS decoration |
| File output | Must have |
| Script execution（Python/Node.js） | Missing -> skip automatic packaging and SVG conversion |
Principle: Check the actual list of callable tools, and use whatever is available.
Path Conventions
The following paths are used repeatedly throughout the workflow, and should be determined immediately after Step 1 is completed:
| Variable | Meaning | How to Obtain |
|---|---|---|
SKILL_DIR |
The absolute path of the directory where this SKILL.md is located | That is, the directory where SKILL.md is read when the Skill is triggered |
OUTPUT_DIR |
Root directory for product output | Under the user's current working directory ppt-output/(on first use mkdir -p create) |
All subsequent paths are based on these two variables and will not be explained repeatedly.
Input Modes and Complexity Assessment
Entry Point Assessment
| Entry Point | Example | Which Step to Start From |
|---|---|---|
| Pure topic | "Make a Dify company introduction PPT" | Step 1 complete workflow |
| Topic + requirements | "15-page AI security PPT, dark style" | Step 1 (skip some known questions) |
| Source materials | "Turn this report into a PPT" | Step 1 (materials as the main focus) |
| Existing outline | "I already have an outline, generate the design draft" | Step 4 or 5 |
Step-Skipping Rules
When skipping preceding steps, the corresponding dependent outputs must be completed:
| Starting Step | Missing Dependency | How to Complete |
|---|---|---|
| Step 4 | Text content for each page | First use Prompt #3 to assign generated content to each page |
| Step 5 | Planning draft JSON | Provided by user or execute Step 4 first |
Complexity-adaptive
Automatically adjust process granularity based on target page count:
| Scale | Page count | Research | Search | Planning | Generation |
|---|---|---|---|---|---|
| Lightweight | <= 8 pages | 3-question simplified version (scenario + audience + supplementary information) | 3-5 queries | Step 3 can be completed in one step merged with Step 4 | Generate page by page |
| Standard | 9-18 pages | Full 7 questions | 8-12 queries | Full process | Batch by Part, 3-5 pages per batch |
| Large | > 18 pages | Full 7 questions | 10-15 queries | Full process | Batch by Part, 3-5 pages per batch, confirm between batches |
6-step Pipeline
Step 1: Requirements research [STOP -- must wait for user reply]
Skipping is prohibited. No matter how simple the topic is, you must ask questions and wait for the user's reply before continuing. Do not make decisions for the user.
Execution: Use references/prompts.md Prompt #1
- Search for topic background information (3-5 items)
- Choose the full 7 questions or the simplified 3 questions based on complexity, and send them to the user all at once
- Wait for user reply(blocking point)
- Organize into requirements JSON
7-question three-level progressive structure(in lightweight mode, only ask questions 1, 2, and 7):
| Level | Question | What it determines |
|---|---|---|
| Scenario level | 1. Presentation scenario (live/self-reading/training) | Information density and visual style |
| Scenario level | 2. Core audience (dynamically generated profile) | Professional depth and persuasion strategy |
| Scenario level | 3. Desired action (decision/understanding/execution/changing cognition) | Final orientation of content arrangement |
| Content level | 4. Narrative structure (problem->solution/popular science/comparison/timeline) | Outline skeleton logic |
| Content level | 5. Content focus (dynamically generated from search results, multiple selections allowed) | Theme weight of each Part |
| Content level | 6. Persuasion elements (data/cases/authority/methods, multiple selections allowed) | Preferred card content types |
| Execution level | 7. Supplementary information (speaker/brand color/must include/must avoid/page count/image preferences) | Specific execution details |
Output: Requirements JSON (topic + requirements)
Step 2: Material collection
Take stock of all information acquisition capabilities and use them all.
Execution：
- Plan queries based on the topic (for quantity, refer to the complexity table)
- Search in parallel using all available information acquisition tools
- Summarize each group of results
Output: Search result set JSON
Step 3: Outline Planning
Execute: Use references/prompts.md Prompt #2 (Outline Architect v2.0)
Methodology: Pyramid Principle -- conclusion first, subsumed under the above, grouped by category, logical progression
Self-check: Page count meets requirements / each part >= 2 pages / key points backed by data
Output：[PPT_OUTLINE] JSON
Step 4: Content Allocation + Planning Draft [recommend waiting for user confirmation]
Combine content allocation and planning draft generation into one step. While thinking about what content should go on each page, decide the layout and card types at the same time, which is more natural and efficient.
Execute: Use references/prompts.md Prompt #3 (Content Allocation and Planning Draft)
Key Points：
- Precisely map the searched materials to each page
- Design a multi-layered content structure for each page (main card 40-100 words + data highlights + supporting points)
- Also determine the page_type / layout_hint / cards[] structure
- Each content page has at least 3 cards + 2 card_types + 1 data card
- For layout selection, refer to
references/bento-grid.mddecision matrix
Show the user an overview of the planning draft; recommend waiting for user confirmation before proceeding to Step 5.
Output: Per-page planning card JSON array -> save as OUTPUT_DIR/planning.json
Step 5: Style Decision + Design Draft Generation
Divided into three sub-steps,the order must not be reversed：
5a. Style Decision
Execute: Read references/styles/index.md main index (including decision matrix), match one of the 26 preset styles by topic keywords
The 26 styles are grouped into 5 sections(detailed JSON definitions are in the section files):
| Section | Count | Style ID | Section File |
|---|---|---|---|
| Dark Professional | 7 | dark_tech / xiaomi_orange / luxury_purple / nocturne_violet / cyberpunk_neon / chrome_y2k / noir_film | references/styles/dark.md |
| Light Premium | 8 | blue_white / fresh_green / minimal_gray / mocha_editorial / medical_pulse / earth_concrete / champagne_gold / liquid_glass | references/styles/light.md |
| Vibrant Bold | 4 | vibrant_rainbow / kindergarten_pop / bauhaus_block / candy_pastel | references/styles/vibrant.md |
| Eastern Culture | 3 | royal_red / sakura_wabi / ink_jade | references/styles/cultural.md |
| Natural/Retro | 4 | botanic_forest / safari_savanna / retro_70s / gov_authority | references/styles/natural.md |
Style Preview: Execute python3 SKILL_DIR/scripts/gallery.py to generate ppt-output/style-gallery/index.html, open in a browser to visually compare the 26 styles.
Must-read：references/typography.md(typography rules: letter-spacing / tabular-nums / OpenType / serif italic mixed typesetting / drop cap / asymmetric grid / three-tier font stack fallback / subtle texture)
Output: Style definition JSON -> save as OUTPUT_DIR/style.json
5b. Smart Image Matching (according to user preference)
Execute after confirming the user's image preference in the requirements research (question 7 of Step 1). If the user chooses "no images needed", skip this.
Image Timing
Before generating the HTML for each page, before, first generate the image for that page. At least 1 image per page (cover page and section cover pages must have them); after generation, save to OUTPUT_DIR/images/。
generate_image prompt construction formula
The prompt must satisfy all 4 dimensionsat the same time, assembled according to the following formula:
[内容主题] + [视觉风格] + [画面构图] + [技术约束]
| Dimension | Description | Example |
|---|---|---|
| Content Theme | Extract from the core concept of that page's planning draft JSON, specific to scene/object | "DMSO molecular purification process, crystallization flask with clear liquid" |
| Visual Style | Align with the color scheme and emotional tone of style.json | Dark tech -> "deep blue dark tech background, subtle cyan glow, futuristic" |
| Image composition | Determined by how the image is placed on the page | Right-side semi-transparent -> "clean composition, main subject on left, fade to transparent on right" |
| Technical constraints | Fixed suffix to ensure output quality | "no text, no watermark, high quality, professional illustration" |
Style and image keyword correspondence
| PPT style | Image style keywords |
|---|---|
| Dark tech | dark tech background, neon glow, futuristic, digital, cyber |
| Xiaomi orange | minimal dark background, warm orange accent, clean product shot, modern |
| Blue-white business | clean professional, light blue, corporate, minimal, bright |
| Vermilion palace wall | traditional Chinese, elegant red gold, ink painting, cultural |
| Fresh and natural | fresh green, organic, nature, soft light, watercolor |
| Purple-gold luxury | luxury, purple gold, premium, elegant, metallic |
| Minimalist gray-white | minimal, grayscale, clean, geometric, academic |
| Vibrant rainbow | colorful, vibrant, energetic, playful, gradient, pop art |
Adjust by page type
| Page type | Image characteristics | Prompt additional keywords |
|---|---|---|
| Cover page | Topic overview, visual impact | "hero image, wide composition, dramatic lighting" |
| Chapter cover | Symbolic visual for the chapter topic | "symbolic, conceptual, centered composition" |
| Content page | Supporting explanation, should not overshadow the main content | "supporting illustration, subtle, background-suitable" |
| Data page | Abstract data visualization atmosphere | "abstract data visualization, flowing lines, tech" |
Prohibitions
- Text must not appear in images (AI-generated text is poor quality)
- Colors that conflict with the page color scheme are prohibited (dark themes with dark images, light themes with light images)
- Decorative images unrelated to the content are prohibited (each image must have a semantic connection to that page's content)
- Reusing the same prompt is prohibited (each page's image must be unique)
Artifacts：OUTPUT_DIR/images/ Image files under
5c. Page-by-page HTML design draft generation
Execution: Use references/prompts.md Prompt #4 + references/bento-grid.md
Skipping the planning draft and generating directly is prohibited. Each page must first have the Step 4 structure JSON.
Per-page prompt assembly formula：
Prompt #4 模板
+ 风格定义 JSON（5a 产物）[必须]
+ 该页策划稿 JSON（Step 4 产物，含 cards[]/card_type/position/layout_hint）[必须]
+ 该页内容文本（Step 4 产物）[必须]
+ 配图路径（5b 产物）[可选 -- 无配图时省略 IMAGE_INFO 块]
Core design constraints(full list see inside Prompt #4):
- Canvas 1280x720px, overflow:hidden
- All colors must be referenced through CSS variables; hardcoding is prohibited
- Any visually visible element must be a real DOM node; prefer inline SVG for graphics
- Prohibited:
::before/::afterpseudo-elements for visual decoration; prohibited:conic-gradient; prohibited: CSS border triangles - Images integrated into the design: fade blending / color overlay / atmospheric background / cropped viewport / circular cropping (techniques see Prompt #4)
Batching strategy: Generate in batches by Part, 3-5 pages per batch. After each batch is completed, write the HTML to the OUTPUT_DIR/slides/ directory, then start the next batch. This avoids context explosion while ensuring style consistency within the same Part.
Cross-page visual narrative(give the PPT a sense of rhythm, not just a pile of independent pages):
| Strategy | Rule | Reason |
|---|---|---|
| Density alternation | High-density pages (mixed grid/hero style) followed by low-density pages (chapter cover/single focus), creating a rhythm of tension and relaxation | 3+ consecutive high-density content pages will cause audience visual fatigue |
| Chapter Color Progression | Part 1 cards mainly use accent-1, Part 2 uses accent-2, Part 3 uses accent-3 ... each chapter switches to a different accent primary color | Use color to let the audience subconsciously perceive chapter transitions |
| Cover-End Echo | The visual elements of the ending page echo those of the cover page (same decorative patterns, symmetrical layout), giving a sense of complete closure | Echoing the beginning and end is the most basic narrative aesthetic |
| Progressive Reveal | When the same concept unfolds across multiple pages, visual complexity should increase progressively (page 1 simple color blocks -> page 2 add data -> page 3 complete chart) | Guide the audience to gradually deepen their understanding |
Output: one HTML file per page -> OUTPUT_DIR/slides/
Step 6: Post-processing [Required -- Execute immediately after HTML generation]
Skipping is prohibited. After HTML generation, the following four steps must be executed automatically; do not stop at preview.html.
slides/*.html --> preview.html --> svg/*.svg --> presentation.pptx
Dependency check(automatically executed on first run):
pip install python-pptx lxml Pillow 2>/dev/null
Execute in sequence：
-
Merge preview -- run
html_packager.pypython3 SKILL_DIR/scripts/html_packager.py OUTPUT_DIR/slides/ -o OUTPUT_DIR/preview.html -
SVG conversion -- run
html2svg.py(direct DOM to SVG, preserving<text>editable)Important: The HTML design draft must comply with the pipeline compatibility rules in
references/pipeline-compat.md, otherwise problems such as missing elements and misaligned positions will occur after conversion.python3 SKILL_DIR/scripts/html2svg.py OUTPUT_DIR/slides/ -o OUTPUT_DIR/svg/The underlying layer uses dom-to-svg (automatically installed); the first run will bundle with esbuild. Fallback: If Node.js is unavailable or dom-to-svg installation fails, skip this step and step 3, and only output preview.html.
-
PPTX generation -- run
svg2pptx.py(OOXML native SVG embedding, editable in PPT 365)python3 SKILL_DIR/scripts/svg2pptx.py OUTPUT_DIR/svg/ -o OUTPUT_DIR/presentation.pptx --html-dir OUTPUT_DIR/slides/In PPT 365, right-click the image -> "Convert to Shape" to edit text and shapes.
-
Notify the user -- inform them of the output locations and how to use them:
preview.html-- open in a browser to preview page turningpresentation.pptx-- PPTX (right-click -> "Convert to Shape" to edit)svg/-- each SVG can also be dragged into PPT individually- If steps 2-3 were skipped due to fallback, explain the reason and inform the user that they can rerun after manually installing Node.js
Output：preview.html + svg/*.svg + presentation.pptx
Output directory structure
ppt-output/
slides/ # 每页 HTML
svg/ # 矢量 SVG（可导入 PPT 编辑）
images/ # AI 配图
preview.html # 可翻页预览
presentation.pptx # 可编辑 PPTX（右键"转换为形状"）
outline.json # 大纲
planning.json # 策划稿
style.json # 风格定义
Quality self-check
| Dimension | Check item |
|---|---|
| Content | Each page >= 2 information cards / >= 60% of content pages contain data / chapters have progression |
| Visual | Consistent global style / unified illustration style / cards do not overlap / text does not overflow |
| Technical | Unified CSS variables / compliance with SVG-friendly constraints / HTML can be rendered by Puppeteer / pipeline-compat.md prohibited list check |
Resource routing table (field -> folder)
Each field in the planning draft JSON determines which directory the corresponding resource is extracted from:
- Field routing:
layout_hint→layouts/、page_type→page-templates/、card_type→blocks/、chart_type→charts/
| Field | Value | Routes to | Example |
|---|---|---|---|
layout_hint |
asymmetric / hero-top / l-shape / mixed-grid / primary-secondary / single-focus / symmetric / t-shape / three-column / waterfall | references/layouts/<name>.md |
Primary-secondary combination -> references/layouts/primary-secondary.md |
page_type |
cover / toc / section / end | references/page-templates/<name>.md |
Cover -> references/page-templates/cover.md |
card_type |
text / data / list / quote / timeline / comparison / diagram / image-hero / matrix-chart / people | references/blocks/<name>.md |
Data card → references/blocks/card-styles.md |
chart_type |
progress-bar / ring / sparkline / radar / funnel / kpi / metric-row / waffle / rating / timeline / treemap / comparison-bar / stacked-bar | references/charts/<name>.md |
Radar → references/charts/radar.md |
Step 0/1 Interview Template Rules
Step 0 Default Mandatory Templating: The main agent must first generate OUTPUT_DIR/runtime/prompt-interview.md, then ask the user based on the rendered result; during the interview runtime, the template must be chosen between tpl-interview-structured-ui.md and tpl-interview-text-fallback.md according to capability.
Step 0 Prefer Structured Interview UI: As long as the current CLI provides any native questioning capability equivalent to AskUserQuestion / request_user_input , the main agent must preferentially use the structured interview UI; when unsupported, fall back to tpl-interview-text-fallback.md。
Step 0 Sole Exception: Only when the prompt generation in Step 0 encounters a genuine script interface failure, and it has been determined that BLOCKED_SCRIPT_INTERFACE , is the main agent allowed to ask directly; however, the coverage dimensions must not be lower than the final requirements of prompt-interview.md .
Detailed template:references/prompts/tpl-interview.md · references/prompts/tpl-interview-structured-ui.md · references/prompts/tpl-interview-text-fallback.md
Reference File Index
| File | When to Read | Key Content |
|---|---|---|
references/prompts.md |
Before each step's generation (merged version) | 5 sets of Prompt templates (research/outline/planning/design/notes) |
references/prompts/*.md |
Modular version (23 files) | Prompt templates split by step + module + tpl |
references/playbooks/*.md |
Execution manual for each step (11 files) | Execution playbook for each phase of outline / research / source / style / step4 |
references/styles/index.md |
Step 5a | 26 preset style index + decision matrix + JSON Schema |
references/styles/{dark,light,vibrant,cultural,natural}.md |
After selecting a style in Step 5a | Complete JSON + CSS variables + Mock links for all styles in that section |
references/typography.md |
Step 5c | 14 typography iron rules (letter-spacing/tabular-nums/OpenType/serif italic mixed typesetting/font stack fallback) |
references/charts/index.md |
When Step 5c involves data visualization | 18 chart index + decision matrix |
references/charts/{basic,advanced,complex}.md |
After selecting a chart | Complete HTML templates (8 basic / 6 advanced / 4 ECharts-level) |
references/charts/<chart_type>.md |
Fine-grained specification for a single chart | sunbigfly-style single-file charts (13) |
references/layouts/*.md |
Step 5c layout_hint routing | 10 layouts each as separate files (asymmetric / hero-top / l-shape etc.) |
references/blocks/*.md |
Step 5c card_type routing | 9 reusable card prototypes (card-styles / comparison / diagram / quote etc.) |
references/page-templates/*.md |
Step 5c page_type routing | 4 page templates (cover / end / section / toc) |
references/principles/*.md |
Step 4-5 self-check and principles | 8 design principles + failure-modes (cognitive-load / color-psychology / composition / data-visualization / narrative-arc / runtime-failure-modes / visual-hierarchy) |
references/design-runtime/*.md |
Step 5c design runtime | css-weapons / data-type-decoration-mapping / data-type-visual-mapping / design-specs / director-command-rules-examples |
references/bento-grid.md |
Step 5c | 7 layout precise coordinates + 5 card types + decision matrix |
references/method.md |
First-time understanding | Core concepts and methodology |
references/pipeline-compat.md |
When generating Step 5c design drafts | CSS prohibited list + image paths + font size mixed typesetting + SVG text + donut chart + svg2pptx notes |
references/cli-cheatsheet.md |
Script invocation reference | Quick reference of complete invocation commands for all scripts |
references/style-system.md |
(Compatibility guide file) | Upgraded to a guide file, redirect to styles/index.md |
Maintenance and Verification
Source-of-truth files：
| Resource | Source of truth location | Purpose |
|---|---|---|
| Step 4 schema | scripts/planning_validator.py |
P4 planning Gate |
| Workflow version | scripts/workflow_versions.py |
Cross-script version number |
| Skill consistency | scripts/check_skill.py |
Documentation/code contract drift check |
Automatic check entry point: After modifying prompt / playbook / cheatsheet / Step 4 schema examples, run:
python3 scripts/check_skill.py # 文档与代码合同漂移检查
python3 scripts/planning_validator.py # 策划稿 schema 校验
python3 scripts/contract_validator.py # 各 phase 间 JSON 合同校验
python3 scripts/visual_qa.py # 视觉 QA 双层断言（planning + html）
python3 scripts/smoke_test.py # 我们简化版端到端冒烟测试
python3 scripts/smoke_skill.py # sunbigfly 完整版冒烟测试