PPT Agent -- Professional Full-Process Presentation Generation#

Core Philosophy#

Mimics the complete workflow of a professional PPT design company (priced at 10,000+ RMB per page), not "give an outline and apply a template":

1. Research before generation -- Fill content with real data, never fabricate
2. Separate planning from design -- Verify information structure first, then apply visual packaging
3. Content-driven layout -- Bento Grid card-style layout, each page's layout determined by its content
4. Consistent global style -- Lock in style first, then generate page by page, ensuring cross-page consistency
5. Smart illustrations -- Use image generation capabilities to add illustrations for each page (available in most environments)

---

Environment Setup [Required for First Use]#

Node.js Environment#

China Mainland mirror installation (must set, otherwise puppeteer Chrome binary download will fail):

bash

export PUPPETEER_DOWNLOAD_HOST=https://storage.googleapis.com.cnpmjs.org
npm install -g puppeteer --unsafe-perm
npm install -g dom-to-svg esbuild

Verification: node -e "require('puppeteer'); console.log('puppeteer OK')"

If full puppeteer fails to install (Chrome download blocked in China mainland), scripts will automatically fall back to puppeteer-core with system Chrome at /usr/bin/google-chrome. You can also install it directly:

bash

npm install -g puppeteer-core

Python Environment#

bash

pip install python-pptx lxml Pillow

---

Pipeline Mandatory Declaration [Red Lines]#

The following rules must not be violated. Any bypass will cause severe degradation in output quality.

Six-Step Pipeline Order is Fixed, No Skipping#

text

Step 1 → Step 2 → Step 3 → Step 4 → Step 5 → Step 6

Prohibited Behaviors#

• ❌ Skip Step 1 and directly generate PPT
• ❌ Enter Step 5c without a planning draft
• ❌ Stop at preview.html without executing SVG and PPTX
• ❌ Use other tools/pipelines to replace this workflow

Only Allowed Degradation#

• Node.js unavailable → Skip SVG branch, output preview.html only. Notify user.
• Python unavailable → Skip SVG + PNG + PPTX branches, output preview.html only. Notify user and wait for feedback.
• Puppeteer unavailable → Skip PNG branch (visual QA also skipped). SVG branch continues.
• Vision model unavailable → Skip visual audit in visual_qa.py, DOM assertion still runs.

Step Enforcement Levels#

StepEnforcement LevelStep 1STOP -- Cannot skip, must wait for user replyStep 2-3Cannot skipStep 4Cannot skip, must wait for user confirmation of outlineStep 5 internalFixed order: 5a → 5b → 5cStep 6Cannot skip, must execute all post-processing pipeline

---

Environment Awareness#

Self-reflect on the agent's tool capabilities before starting work:

CapabilityDegradation StrategyInformation retrieval (search/URL/docs/knowledge base)All missing -> rely on user-provided materialsImage generation (available in most environments)Missing -> pure CSS decoration insteadFile outputMust haveScript execution (Python/Node.js)Missing -> skip auto-packaging and SVG conversion

Principle: Check the actually callable tool list, use whatever is available.

---

Path Conventions#

Paths used repeatedly throughout the process. Determine immediately after Step 1:

VariableMeaningHow to GetSKILL_DIRAbsolute path of the directory where this SKILL.md residesThe directory from which SKILL.md is read when the skill is triggeredOUTPUT_DIROutput root directoryppt-output/ under the user's current working directory (mkdir -p on first use)

All subsequent paths are based on these two variables and will not be explained again.

---

Input Modes and Complexity Assessment#

Entry Detection#

EntryExampleStart fromTopic only"Make a Dify company introduction PPT"Step 1 full flowTopic + requirements"15-page AI security PPT, dark tech style"Step 1 (skip some known issues)Source material"Turn this report into a PPT"Step 1 (material-focused)Existing outline"I have an outline, generate the design"Step 4 or 5

Skip Rules#

When skipping pre-requisite steps, must complete corresponding dependent outputs:

Starting StepMissing DependencyHow to FillStep 4Page content textFirst use Prompt #3 to generate content allocation for each pageStep 5Planning draft JSONUser provides or execute Step 4 first

Complexity Adaptation#

Automatically adjust process granularity based on target page count:

ScalePagesResearchSearchPlanningGenerationLight<= 8 pages3-question abbreviated version (scenario + audience + supplementary info)3-5 queriesStep 3 can be merged with Step 4Page by pageStandard9-18 pagesFull 7 questions8-12 queriesFull processBy Part, 3-5 pages per batchLarge> 18 pagesFull 7 questions10-15 queriesFull processBy Part, 3-5 pages per batch, confirm between batches

---

Breakpoint Recovery#

The workflow is stateless. After interruption, the Main Agent scans existing artifacts on disk to determine the recovery point automatically.

Recovery Logic#

python

def find_recovery_point(run_dir: Path) -> str:
    """Scan existing artifacts to determine recovery point."""
    milestones = [
        ("presentation-svg.pptx", "P5-SVG-DONE"),
        ("presentation-png.pptx", "P5-PNG-DONE"),
        ("png/slide-*.png", "P4-VisualQA-DONE"),
        ("slides/slide-*.html", "P4-PAGE-DONE"),
        ("style.json", "P3.5-STYLE-LOCKED"),
        ("outline.txt", "P3-OUTLINE-DONE"),
        ("search.txt", "P2-SEARCH-DONE"),
        ("requirements-interview.txt", "P1-REQUIREMENTS-DONE"),
    ]
    for pattern, step in reversed(milestones):
        matches = list(run_dir.glob(pattern))
        if matches:
            return step
    return "P0-START"

Recovery Rules#

RuleDescriptionNo state filesThe workflow does not rely on any progress state filesScan disk artifactsRecovery point is inferred from existing files on diskPartial completion OKEven one page's HTML exists = P4 is considered reached for that pageAgent decidesThe Main Agent decides which Subagents to spawn based on scan resultsNo rollbackArtifacts already written are never deleted during recovery

Artifact Existence = Milestone Reached#

ArtifactMilestonerequirements-interview.txtP1 Completesearch.txtP2 Completeoutline.txtP3 Completestyle.jsonP3.5 Style Lockedslides/slide-N.html (any)P4 Page generation in progresspng/slide-N.png (all)P4 Visual QA Completepresentation-svg.pptxP5 SVG Export Completepresentation-png.pptxP5 PNG Export Complete

---

Subagent Scheduling (Subagent Dispatch)#

Each stage has a dedicated Subagent to avoid Context pollution. Context isolation ensures each Subagent only carries its own stage's information.

Subagent Architecture#

text

Main Agent (Decision + Dispatch)
    │
    ├── ResearchAgent ──→ search.txt
    │       Model: MUST pass --model parameter
    │
    ├── OutlineAgent ──→ outline.txt
    │       Model: MUST pass --model parameter
    │
    ├── StyleAgent ──→ style.json
    │       Model: MUST pass --model parameter
    │
    ├── PlanningAgent ──→ planning-N.json (per page)
    │       Model: MUST pass --model parameter
    │
    ├── PageAgent-1 ──→ slide-1.html (parallel)
    ├── PageAgent-2 ──→ slide-2.html (parallel)
    │         ... (all pages parallel)
    └── PageAgent-N ──→ slide-N.html (parallel)
        Model: MUST pass --model parameter for each

Main Agent ← All Subagents complete ← Step 6 Post-processing

Subagent Rules#

RuleDescriptionMust specify --modelEvery Subagent MUST receive explicit --model parameter, no default fallbackContext isolationEach Subagent only reads/writes its own stage's artifactsFailure isolationSingle Subagent failure does not block other SubagentsRetry on failureFailed Subagent retries up to 2 times before escalation to Main Agent

Artifact Naming Convention#

ArtifactFilenameRequirementsrequirements-interview.txtSearch Resultssearch.txtOutlineoutline.txtStyle Definitionstyle.jsonPlanning Draftplanning-N.json (N = page number)Design Draftslides/slide-N.htmlScreenshotslides/slide-N.pngSVGsvg/slide-N.svg

---

6-Step Pipeline#

Step 1: Requirements Interview [STOP -- Cannot Skip]#

Cannot skip. No matter how simple the topic, must ask questions and wait for user reply before continuing. Do not make decisions for the user.

Execute: Use references/prompts.md Prompt #1

1. Search topic background information (3-5 items)
2. Based on complexity, choose full 7 questions or abbreviated 3 questions, send to user in one go
3. Wait for user reply (blocking point)
4. Organize into requirements JSON

7-Question Three-Tier Structure (light mode only asks questions 1, 2, 7):

TierQuestionDeterminesScenario1. Presentation scenario (live/self-reading/training)Information density and visual styleScenario2. Core audience (dynamically generated profile)Professional depth and persuasion strategyScenario3. Desired action (decision/understanding/execution/change perception)Final content arrangement directionContent4. Narrative structure (problem->solution/educational/comparison/timeline)Outline skeleton logicContent5. Content focus (dynamically generated from search results, multi-select)Each Part's theme weightContent6. Persuasion elements (data/case/authority/method, multi-select)Card content type preferencesExecution7. Supplementary info (speaker/brand colors/must-include/must-avoid/page count/illustration preference)Specific execution details

Output: Requirements JSON (topic + requirements)

---

Step 2: Information Gathering#

Take inventory of all information retrieval capabilities and use them all.

Execute:

1. Plan queries based on topic (quantity reference complexity table)
2. Use all available information retrieval tools for parallel search
3. Summarize each group of results

Output: Search results collection JSON

---

Step 3: Outline Planning#

Execute: Use references/prompts.md Prompt #2 (Outline Architect v2.0)

Methodology: Pyramid Principle -- Conclusion first, above to below, categorize and group, logical progression

Self-check: Page count meets requirements / each part >= 2 pages / key points have data support

Output: [PPT_OUTLINE] JSON

---

Step 4: Content Allocation + Planning Draft [Cannot Skip -- Must Wait for User Confirmation of Outline]#

Combine content allocation and planning draft generation into one step. While thinking about what content each page should have, also decide layout and card types, making it more natural and efficient.

Execute: Use references/prompts.md Prompt #3 (Content Allocation and Planning Draft)

Key Points:

• Precisely map search materials to each page
• Design multi-layer content structure for each page (main card 40-100 chars + data highlight + supporting points)
• Also determine page_type / layout_hint / cards[] structure
• Each content page at least 3 cards + 2 card_types + 1 data card
• Layout selection reference references/bento-grid.md decision matrix

Show planning draft overview to user, recommend waiting for user confirmation before entering Step 5.

Output: Per-page planning card JSON array -> Save as OUTPUT_DIR/planning.json

---

Step 5: Style Decision + Design Draft Generation#

Split into three sub-steps, order cannot be reversed:

5a. Style Decision

Execute: Read references/style-system.md, select or infer style

Match one of 8 preset styles based on topic keywords (dark tech / xiaomi orange / blue white business / royal red / fresh green / luxury purple / minimal gray / vibrant rainbow), detailed matching rules and full JSON definitions in references/style-system.md.

Output: Style definition JSON -> Save as OUTPUT_DIR/style.json

5b. Smart Illustrations [Execute Based on Step 1 Question 7 Answer]

If user selected "no illustrations needed" in Step 1, skip this entire section.

Step 1 Answer Routing:

Step 1 AnswerAction"User provides images"Use images from user-provided paths"AI generation"Call image_generate tool"Unsplash"Call Unsplash API

Illustration Timing

Before generating each page's HTML, generate that page's illustration first. At least 1 per page (cover page, section cover must have), save to OUTPUT_DIR/images/.

⚠️ Image Path Rule -- MUST FOLLOW: All images must be downloaded to OUTPUT_DIR/images/ before generating HTML. Use <img src="images/xxx.png"> with relative paths in HTML. Never reference external URLs (Unsplash etc.) directly in HTML -- they cannot load under file:// protocol.

Degradation Chain (automatic degradation, no need to ask user again):

text

AI generation (image_generate)
  └─ Tool available → Generate image
  └─ Tool unavailable/failed → Unsplash API
                                 └─ Key configured → Search and get
                                 └─ Key not configured/failed → Pure CSS decoration degradation

User provides images
  └─ Path valid and semantically matches → Use that image
  └─ Path invalid/semantically mismatched → Degrade to Unsplash or CSS decoration

Unsplash
  └─ UNSPLASH_ACCESS_KEY configured → Call API
  └─ Key not configured/failed → Pure CSS decoration degradation

Image Quantity by Page Type:

Page TypeWith IllustrationsWithoutCover pageMust havePure CSS decorationSection coverMust havePure CSS decorationContent pageOptional 1 per pageNo imageEnd pageOptionalPure CSS decoration

Output: Illustration files under OUTPUT_DIR/images/ (if any)

image_generate Prompt Construction Formula

Prompt must satisfy 4 dimensions simultaneously, assembled by formula:

[Content Topic] + [Visual Style] + [Image Composition] + [Technical Constraints]

DimensionDescriptionExampleContent topicExtracted from that page's planning draft JSON core concept, specific to scene/object"DMSO molecular purification process, crystallization flask with clear liquid"Visual styleAligned with style.json color scheme and emotional toneDark tech -> "deep blue dark tech background, subtle cyan glow, futuristic"Image compositionDecided by how the image is placed in the pageRight side semi-transparent -> "clean composition, main subject on left, fade to transparent on right"Technical constraintsFixed suffix ensuring output quality"no text, no watermark, high quality, professional illustration"

Style and Illustration Keyword Mapping

PPT StyleIllustration Style KeywordsDark techdark tech background, neon glow, futuristic, digital, cyberXiaomi orangeminimal dark background, warm orange accent, clean product shot, modernBlue white businessclean professional, light blue, corporate, minimal, brightRoyal redtraditional Chinese, elegant red gold, ink painting, culturalFresh greenfresh green, organic, nature, soft light, watercolorLuxury purpleluxury, purple gold, premium, elegant, metallicMinimal grayminimal, grayscale, clean, geometric, academicVibrant rainbowcolorful, vibrant, energetic, playful, gradient, pop artGradient bluegradient blue, tech, futuristic, clean, digital, professionalWarm sunsetwarm orange, sunset, lifestyle, travel, food, cozy lightingNordic whiteminimal, white, clean, scandinavian, lifestyle, brightCyber punkneon, cyber, dark, futuristic, gaming, vibrant, holographicElegant goldgold, luxury, elegant, premium, metallic, champagneOcean depthocean blue, deep sea, marine, aquatic, serene, gradientRetro filmvintage, film grain, retro, warm tones, nostalgic, cinematicCorporate bluecorporate, professional, blue, business, formal, trustworthy

Adjustment by Page Type

Page TypeImage CharacteristicsPrompt Additional KeywordsCover pageTopic overview, visual impact"hero image, wide composition, dramatic lighting"Section coverSymbolic visual of that chapter's topic"symbolic, conceptual, centered composition"Content pageSupporting illustration, not overwhelming"supporting illustration, subtle, background-suitable"Data pageAbstract data visualization atmosphere"abstract data visualization, flowing lines, tech"

Prohibited Items

• No text in images (AI-generated text quality is poor)
• No colors conflicting with page color scheme (dark theme with dark images, light theme with light images)
• No irrelevant decorative images (every image must be semantically related to that page's content)
• No duplicate prompts (each page's image must be unique)

Output: Illustration files under OUTPUT_DIR/images/

5c. PageAgent Parallel Generation

Cannot skip planning draft and directly generate. Each page must first have Step 4's structure JSON.

Parallel Scheduling: All pages are generated in parallel via PageAgent-N subagents. Each PageAgent is responsible for one page only.

Parallel Strategy:

ScalePagesStrategySmall<= 5 pagesAll pages parallelStandard6-18 pagesAll pages parallel (independent)Large> 18 pagesBy Part parallel, pages within Part parallel

PageAgent Workflow:

text

PageAgent-N
    │
    ├── 1. Read planning-N.json
    ├── 2. Read style.json
    ├── 3. Read images/planning-N.png (if exists)
    ├── 4. Generate slide-N.html
    ├── 5. DOM self-check (overflow / pseudo-elements / hardcoded colors)
    └── 6. Output: --- PAGE N COMPLETE ---

Failure Handling:

• Single page failure does not affect other pages
• Failed page enters PagePatchAgent retry queue (max 2 retries)
• Main Agent waits for all PageAgents to complete before proceeding to Step 6

Per-Page Prompt Assembly Formula:

text

Prompt #4 template
+ Style definition JSON (5a output) [required]
+ That page's planning draft JSON (Step 4 output, containing cards[]/card_type/position/layout_hint) [required]
+ That page's content text (Step 4 output) [required]
+ Illustration path (5b output) [optional -- omit IMAGE_INFO block when no illustration]

Core Design Constraints (complete checklist in Prompt #4):

• Canvas 1280x720px, overflow:hidden
• All colors referenced via CSS variables, no hardcoding
• All visually visible elements must be real DOM nodes, graphics prefer inline SVG
• Prohibited: ::before/ ::after pseudo-elements for visual decoration, conic-gradient, CSS border triangles
• Illustration integration: fade blend / tinted overlay / ambient background / crop viewport / circular crop (techniques in Prompt #4)

Cross-Page Visual Narrative:

StrategyRuleReasonDensity alternationHigh-density pages followed by low-density pagesAvoid visual fatigueChapter color progressionEach Part uses a different accent main colorUnconsciously perceive chapter transitionsCover-ending echoEnd page echoes cover pageComplete closed-loopProgressive revelationComplexity increases across pagesGuide audience to deeper understanding

Output: One HTML file per page -> OUTPUT_DIR/slides/

---

Step 6: Post-Processing [Must Do -- Execute Immediately After HTML Generation]#

Cannot skip, must execute. After HTML generation, must immediately execute the following pipeline steps.

text

slides/*.html
  ├── html_packager.py --> preview.html
  ├── html2svg.py --> svg/*.svg --> svg2pptx.py --> presentation-svg.pptx
  └── html2png.py --> png/*.png --> png2pptx.py --> presentation-png.pptx

Dependency check (auto-execute on first run):

bash

pip install python-pptx lxml Pillow 2>/dev/null
npm install puppeteer dom-to-svg 2>/dev/null

Execute in order:

1. Merge Preview -- Run html_packager.py bash

   python SKILL_DIR/scripts/html_packager.py OUTPUT_DIR/slides/ -o OUTPUT_DIR/preview.html
   
   

2. SVG Conversion -- Run html2svg.py (DOM direct to SVG, preserves editable <text>)

   Important: HTML design drafts must comply with pipeline compatibility rules in references/pipeline-compat.md, otherwise element loss and position misalignment will occur after conversion.

   bash

   python SKILL_DIR/scripts/html2svg.py OUTPUT_DIR/slides/ -o OUTPUT_DIR/svg/
   
   

   Uses dom-to-svg underneath (auto-installs), esbuild bundles on first run. Degradation: If dom-to-svg installation fails, SVG branch will abort and notify user. PNG branch continues independently.

3. SVG PPTX Export -- Run svg2pptx.py (OOXML native SVG embedding, PPT 365 editable) bash

   python SKILL_DIR/scripts/svg2pptx.py OUTPUT_DIR/svg/ -o OUTPUT_DIR/presentation-svg.pptx --html-dir OUTPUT_DIR/slides/
   
   

   In PPT 365, right-click image -> "Convert to Shape" to edit text and shapes.

4. PNG Screenshot -- Run html2png.py (Puppeteer screenshot, parallel execution) bash

   python SKILL_DIR/scripts/html2png.py OUTPUT_DIR/slides/ -o OUTPUT_DIR/png/ --concurrency 4
   
   

   Uses Puppeteer for pixel-perfect screenshots. Concurrency controls parallel screenshot threads. Degradation: If Node.js/Puppeteer unavailable, skip PNG branch entirely.

5. PNG PPTX Export -- Run png2pptx.py (PNG as background, cross-platform 100% visual fidelity) bash

   python SKILL_DIR/scripts/png2pptx.py OUTPUT_DIR/png/ -o OUTPUT_DIR/presentation-png.pptx
   
   

   PNG fills each slide as background. Text is not editable but visuals are pixel-perfect.

6. Notify User -- Inform output location and usage:

   • preview.html -- Open in browser for paginated preview
   • presentation-svg.pptx -- PPTX with editable text and shapes (SVG vectors)
   • presentation-png.pptx -- PPTX with pixel-perfect visuals (PNG backgrounds, text not editable)
   • svg/ -- Each SVG can also be dragged individually into PPT
   • png/ -- PNG screenshots (for Visual QA reference)
   • If SVG branch was skipped, explain reason and tell user they can install Node.js and rerun
   • If PNG branch was skipped, note that PNG screenshots are used for Visual QA only

Output: preview.html + svg/ .svg + png/.png + presentation-svg.pptx + presentation-png.pptx

---

Output Directory Structure#

text

ppt-output/
  slides/                  # Per-page HTML
  svg/                     # Vector SVG (importable into PPT for editing)
  png/                     # PNG screenshots (for Visual QA + PNG PPTX export)
  images/                  # AI illustrations
  preview.html             # Paginated preview
  presentation-svg.pptx    # Editable PPTX (SVG vectors, PPT 365 "Convert to Shape")
  presentation-png.pptx    # Pixel-perfect PPTX (PNG backgrounds, not editable)
  outline.json             # Outline
  planning.json            # Planning draft
  style.json               # Style definition

---

Quality Self-Check#

DimensionCheck ItemsContentEach page >= 2 info cards / >= 60% content pages contain data / chapters have progressionVisualGlobal style consistent / illustration style unified / cards don't overlap / text doesn't overflowTechnicalCSS variables unified / SVG-friendly constraints followed / HTML renderable by Puppeteer / pipeline-compat.md prohibited list checked

---

Reference File Index#

FileWhen to ReadKey Contentreferences/prompts.mdBefore each generation step5 Prompt templates (research/outline/planning/design/notes)references/style-system.mdStep 5a16 preset styles + CSS variables + style JSON modelreferences/bento-grid.mdStep 5c7 layout specs + 12 card types + decision matrixreferences/method.mdFirst-time understandingCore philosophy and methodologyreferences/pipeline-compat.mdDuring Step 5c design draft generationCSS prohibited list + image paths + font size mixing + SVG text + ring charts + svg2pptx notes