Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(workflow): streamline PPT Master guidance

hugohe31793bafe04cc
diff --git a/AGENTS.md b/AGENTS.md
index 7f00bf57..2a61e9b5 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,8 @@
# AGENTS.md
-This file serves as the project entry point for general AI agents. Before executing PPT generation tasks, **you MUST first read `skills/ppt-master/SKILL.md`** for the complete workflow and rules.
+This file is the project entry point for general AI agents.
+
+Before executing any PPT generation task, **you MUST first read [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md)**. That file is the authoritative workflow for project creation, role switching, strict serial execution, quality gates, post-processing, and export.
## Project Overview
@@ -8,93 +10,54 @@ PPT Master is an AI-driven presentation generation system. Through multi-role co
**Core Pipeline**: `Source Document → Create Project → Template Option → Strategist Eight Confirmations → [Image_Generator] → Executor → Post-processing → Export PPTX`
-**Execution Requirements**:
+## Execution Requirements
-- Before starting a PPT task, read `skills/ppt-master/SKILL.md` first
-- To create a template independently, read `skills/ppt-master/workflows/create-template.md`
-- Role-specific rules and technical constraints are in `skills/ppt-master/references/`
-- ⚠️ **Strict serial execution**: Every Step in the pipeline MUST be executed sequentially — bundling, batching, or parallelizing Steps is FORBIDDEN
-- ⚠️ **SVG generation must stay in the main agent**: During Executor Step 6, SVG pages MUST be generated by the current main agent with full project context. Delegating SVG generation to sub-agents is FORBIDDEN
-- ⚠️ **SVG generation rhythm**: In Executor Step 6, first lock the global design context, then generate SVGs sequentially page by page in one continuous pass. Generating pages in grouped batches (for example, 5 pages at a time) is FORBIDDEN
+- Read [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) before starting a PPT task.
+- For standalone template creation, read [`skills/ppt-master/workflows/create-template.md`](skills/ppt-master/workflows/create-template.md).
+- Role-specific rules live in [`skills/ppt-master/references/`](skills/ppt-master/references/).
+- Technical SVG/PPT constraints live in [`skills/ppt-master/references/shared-standards.md`](skills/ppt-master/references/shared-standards.md).
+- Canvas choices live in [`skills/ppt-master/references/canvas-formats.md`](skills/ppt-master/references/canvas-formats.md).
+- Icon library details live in [`skills/ppt-master/templates/icons/README.md`](skills/ppt-master/templates/icons/README.md).
## Compatibility Boundary
-- This repository is a workflow/skill package, not a conventional app or service scaffold
-- Do NOT assume repository-local conventions such as `.worktrees/`, `tests/`, or mandatory branch setup unless the user explicitly requests them
-- If a generic coding skill conflicts with this repository's instructions, prioritize `skills/ppt-master/SKILL.md` and this file for work inside this repository
+- This repository is a workflow/skill package, not a conventional app or service scaffold.
+- Do NOT assume repository-local conventions such as `.worktrees/`, `tests/`, or mandatory branch setup unless the user explicitly requests them.
+- If a generic coding skill conflicts with this repository's instructions, prioritize [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) and this file for work inside this repository.
+
+## Command Quick Reference
-## Common Commands
+These commands are a convenience summary only. The full step-by-step workflow remains in [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md).
```bash
# Source content conversion
python3 skills/ppt-master/scripts/source_to_md/pdf_to_md.py <PDF_file>
-python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file> # Native: .docx/.html/.epub/.ipynb; pandoc fallback: .doc/.odt/.rtf/.tex/.rst/.org/.typ
+python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file>
python3 skills/ppt-master/scripts/source_to_md/ppt_to_md.py <PPTX_file>
-python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL> # auto-uses curl_cffi if installed (covers WeChat etc.)
-node skills/ppt-master/scripts/source_to_md/web_to_md.cjs <URL> # fallback only; use if curl_cffi is unavailable
+python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL>
# Project management
python3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169
python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_URLs...> --move
python3 skills/ppt-master/scripts/project_manager.py validate <project_path>
-# Image tools
+# Image tools and SVG quality check
python3 skills/ppt-master/scripts/analyze_images.py <project_path>/images
python3 skills/ppt-master/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images
-
-# SVG quality check
python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path>
-# Post-processing pipeline (MUST run sequentially, one at a time — NEVER batch)
+# Post-processing pipeline: run sequentially, one command at a time
python3 skills/ppt-master/scripts/total_md_split.py <project_path>
-# ✅ Confirm no errors before running the next command
python3 skills/ppt-master/scripts/finalize_svg.py <project_path>
-# ✅ Confirm no errors before running the next command
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> -s final
-# Output: exports/<project_name>_<timestamp>.pptx + exports/<project_name>_<timestamp>_svg.pptx
-# Use --only native or --only legacy to generate just one version
```
## Core Directories
-- `skills/ppt-master/SKILL.md` — Main entry point and complete workflow
-- `skills/ppt-master/workflows/create-template.md` — Standalone template workflow
-- `skills/ppt-master/references/` — Role definitions and technical specifications
-- `skills/ppt-master/scripts/` — Tool scripts
-- `skills/ppt-master/scripts/docs/` — Topic-focused script docs (`conversion`, `project`, `svg-pipeline`, `image`, `troubleshooting`)
-- `skills/ppt-master/templates/` — Layout templates, chart templates, icon library
-- `examples/` — Example projects
-- `projects/` — User project workspace
-
-## SVG Technical Constraints
-
-**Banned features**: `mask` | `<style>` | `class` | external CSS | `<foreignObject>` | `textPath` | `@font-face` | `<animate*>` | `<script>` | `<iframe>` | `<symbol>`+`<use>` (`id` inside `<defs>` is a legitimate reference and is NOT banned)
-
-**Conditionally allowed**: `marker-start` / `marker-end` — the referenced `<marker>` must live in `<defs>`, use `orient="auto"`, and its shape must be a triangle (3-vertex closed path/polygon), diamond (4-vertex), or circle/ellipse. The converter maps these to native DrawingML `<a:headEnd>` / `<a:tailEnd>`. See `shared-standards.md` §1.1 for full constraints.
-
-**Conditionally allowed**: `clipPath` on `<image>` — the referenced `<clipPath>` must live in `<defs>` and contain a single shape child (circle, ellipse, rect with rx/ry, path, or polygon). The converter maps these to native DrawingML picture geometry (`<a:prstGeom>` or `<a:custGeom>`). Only supported on `<image>` elements. See `shared-standards.md` §1.2 for full constraints.
-
-**PPT compatibility alternatives**:
-
-| Banned | Alternative |
-|--------|-------------|
-| `rgba()` | `fill-opacity` / `stroke-opacity` |
-| `<g opacity>` | Set opacity on each child element individually |
-| `<image opacity>` | Overlay with a mask layer |
-
-## Canvas Format Quick Reference
-
-| Format | viewBox |
-|--------|---------|
-| PPT 16:9 | `0 0 1280 720` |
-| PPT 4:3 | `0 0 1024 768` |
-| Xiaohongshu (RED) | `0 0 1242 1660` |
-| WeChat Moments | `0 0 1080 1080` |
-| Story | `0 0 1080 1920` |
-
-## Post-processing Notes
-
-- **NEVER** use `cp` as a substitute for `finalize_svg.py`
-- **NEVER** export directly from `svg_output/` — MUST export from `svg_final/` (use `-s final`)
-- Do NOT add extra flags like `--only` to the post-processing commands
-- **NEVER** run the three post-processing steps in a single code block or single shell invocation
+- `skills/ppt-master/SKILL.md` — main workflow authority.
+- `skills/ppt-master/references/` — role definitions and technical specifications.
+- `skills/ppt-master/scripts/` — runnable tool scripts.
+- `skills/ppt-master/scripts/docs/` — topic-focused script docs.
+- `skills/ppt-master/templates/` — layout templates, chart templates, icon library.
+- `examples/` — example projects.
+- `projects/` — user project workspace.
diff --git a/CLAUDE.md b/CLAUDE.md
index 353bde3e..5132f71e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1,6 +1,8 @@
# CLAUDE.md
-This file provides a project overview for Claude Code. Before executing PPT generation tasks, **you MUST first read `skills/ppt-master/SKILL.md`** for the complete workflow and rules.
+This file is the project entry point for Claude Code.
+
+Before executing any PPT generation task, **you MUST first read [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md)**. That file is the authoritative workflow for project creation, role switching, strict serial execution, quality gates, post-processing, and export.
## Project Overview
@@ -8,78 +10,54 @@ PPT Master is an AI-driven presentation generation system. Through multi-role co
**Core Pipeline**: `Source Document → Create Project → Template Option → Strategist Eight Confirmations → [Image_Generator] → Executor → Post-processing → Export PPTX`
-## Common Commands
+## Execution Requirements
+
+- Read [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) before starting a PPT task.
+- For standalone template creation, read [`skills/ppt-master/workflows/create-template.md`](skills/ppt-master/workflows/create-template.md).
+- Role-specific rules live in [`skills/ppt-master/references/`](skills/ppt-master/references/).
+- Technical SVG/PPT constraints live in [`skills/ppt-master/references/shared-standards.md`](skills/ppt-master/references/shared-standards.md).
+- Canvas choices live in [`skills/ppt-master/references/canvas-formats.md`](skills/ppt-master/references/canvas-formats.md).
+- Icon library details live in [`skills/ppt-master/templates/icons/README.md`](skills/ppt-master/templates/icons/README.md).
+
+## Compatibility Boundary
+
+- This repository is a workflow/skill package, not a conventional app or service scaffold.
+- Do NOT assume repository-local conventions such as `.worktrees/`, `tests/`, or mandatory branch setup unless the user explicitly requests them.
+- If a generic coding skill conflicts with this repository's instructions, prioritize [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md) and this file for work inside this repository.
+
+## Command Quick Reference
+
+These commands are a convenience summary only. The full step-by-step workflow remains in [`skills/ppt-master/SKILL.md`](skills/ppt-master/SKILL.md).
```bash
# Source content conversion
python3 skills/ppt-master/scripts/source_to_md/pdf_to_md.py <PDF_file>
-python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file> # Native: .docx/.html/.epub/.ipynb; pandoc fallback: .doc/.odt/.rtf/.tex/.rst/.org/.typ
+python3 skills/ppt-master/scripts/source_to_md/doc_to_md.py <DOCX_or_other_file>
python3 skills/ppt-master/scripts/source_to_md/ppt_to_md.py <PPTX_file>
-python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL> # auto-uses curl_cffi if installed (covers WeChat etc.)
-node skills/ppt-master/scripts/source_to_md/web_to_md.cjs <URL> # fallback only; use if curl_cffi is unavailable
+python3 skills/ppt-master/scripts/source_to_md/web_to_md.py <URL>
# Project management
python3 skills/ppt-master/scripts/project_manager.py init <project_name> --format ppt169
python3 skills/ppt-master/scripts/project_manager.py import-sources <project_path> <source_files_or_URLs...> --move
python3 skills/ppt-master/scripts/project_manager.py validate <project_path>
-# Image tools
+# Image tools and SVG quality check
python3 skills/ppt-master/scripts/analyze_images.py <project_path>/images
python3 skills/ppt-master/scripts/image_gen.py "prompt" --aspect_ratio 16:9 --image_size 1K -o <project_path>/images
-
-# SVG quality check
python3 skills/ppt-master/scripts/svg_quality_checker.py <project_path>
-# Post-processing pipeline (MUST run sequentially, one at a time — NEVER batch)
+# Post-processing pipeline: run sequentially, one command at a time
python3 skills/ppt-master/scripts/total_md_split.py <project_path>
-# ✅ Confirm no errors before running the next command
python3 skills/ppt-master/scripts/finalize_svg.py <project_path>
-# ✅ Confirm no errors before running the next command
python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> -s final
-# Output: exports/<project_name>_<timestamp>.pptx + exports/<project_name>_<timestamp>_svg.pptx
-# Use --only native or --only legacy to generate just one version
```
## Architecture
-- `skills/ppt-master/references/` — AI role definitions and technical specifications
-- `skills/ppt-master/scripts/` — Runnable tool scripts
-- `skills/ppt-master/scripts/docs/` — Topic-focused script docs
-- `skills/ppt-master/templates/` — Layout templates, chart templates, 640+ vector icons
-- `examples/` — Example projects
-- `projects/` — User project workspace
-
-## SVG Technical Constraints (Non-negotiable)
-
-**Text characters (must be well-formed XML)**: typography & symbols (em dash, en dash, ©, ®, →, NBSP, full-width punctuation, emoji…) MUST be written as raw Unicode characters; HTML named entities like `&nbsp;` `&mdash;` `&copy;` `&ndash;` `&reg;` are forbidden. XML reserved characters (`&` `<` `>` `"` `'`) inside text or attribute values MUST be escaped as `&amp;` `&lt;` `&gt;` `&quot;` `&apos;` (e.g. `R&amp;D`, `error &lt; 5%`). See `shared-standards.md` §1.0 for full rules.
-
-**Banned features**: `mask` | `<style>` | `class` | external CSS | `<foreignObject>` | `textPath` | `@font-face` | `<animate*>` | `<script>` | `<iframe>` | `<symbol>`+`<use>` (`id` inside `<defs>` is a legitimate reference and is NOT banned)
-
-**Conditionally allowed**: `marker-start` / `marker-end` — the referenced `<marker>` must live in `<defs>`, use `orient="auto"`, and its shape must be a triangle (3-vertex closed path/polygon), diamond (4-vertex), or circle/ellipse. The converter maps these to native DrawingML `<a:headEnd>` / `<a:tailEnd>`. See `shared-standards.md` §1.1 for full constraints.
-
-**Conditionally allowed**: `clipPath` on `<image>` — the referenced `<clipPath>` must live in `<defs>` and contain a single shape child (circle, ellipse, rect with rx/ry, path, or polygon). The converter maps these to native DrawingML picture geometry (`<a:prstGeom>` or `<a:custGeom>`). Only supported on `<image>` elements. See `shared-standards.md` §1.2 for full constraints.
-
-**PPT compatibility alternatives**:
-
-| Banned | Alternative |
-|--------|-------------|
-| `rgba()` | `fill-opacity` / `stroke-opacity` |
-| `<g opacity>` | Set opacity on each child element individually |
-| `<image opacity>` | Overlay with a mask layer |
-
-## Canvas Format Quick Reference
-
-| Format | viewBox |
-|--------|---------|
-| PPT 16:9 | `0 0 1280 720` |
-| PPT 4:3 | `0 0 1024 768` |
-| Xiaohongshu (RED) | `0 0 1242 1660` |
-| WeChat Moments | `0 0 1080 1080` |
-| Story | `0 0 1080 1920` |
-
-## Post-processing Notes
-
-- **NEVER** use `cp` as a substitute for `finalize_svg.py`
-- **NEVER** export directly from `svg_output/` — MUST export from `svg_final/` (use `-s final`)
-- Do NOT add extra flags like `--only` to the post-processing commands
-- **NEVER** run the three post-processing steps in a single code block or single shell invocation
+- `skills/ppt-master/SKILL.md` — main workflow authority.
+- `skills/ppt-master/references/` — role definitions and technical specifications.
+- `skills/ppt-master/scripts/` — runnable tool scripts.
+- `skills/ppt-master/scripts/docs/` — topic-focused script docs.
+- `skills/ppt-master/templates/` — layout templates, chart templates, icon library.
+- `examples/` — example projects.
+- `projects/` — user project workspace.
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.md
index a8602401..e17cb052 100644
--- a/skills/ppt-master/SKILL.md
+++ b/skills/ppt-master/SKILL.md
@@ -67,7 +67,7 @@ For complete tool documentation, see `${SKILL_DIR}/scripts/README.md`.
|-------|------|---------|
| Layout templates | `${SKILL_DIR}/templates/layouts/layouts_index.json` | Query available page layout templates |
| Visualization templates | `${SKILL_DIR}/templates/charts/charts_index.json` | Query available visualization SVG templates (charts, infographics, diagrams, frameworks) |
-| Icon library | `${SKILL_DIR}/templates/icons/` | Search icons on demand: `ls templates/icons/<library>/ \| grep <keyword>` (libraries: `chunk/`, `tabler-filled/`, `tabler-outline/`) |
+| Icon library | `${SKILL_DIR}/templates/icons/` | See `${SKILL_DIR}/templates/icons/README.md`; search icons on demand with `ls templates/icons/<library>/ \| grep <keyword>` |
## Standalone Workflows
@@ -212,7 +212,7 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images
Read `references/image-generator.md`
-1. Extract all images with status "pending generation" from the design spec
+1. Extract all images with status `Pending` from the design spec
2. Generate prompt document → `<project_path>/images/image_prompts.md`
3. Generate images (CLI tool recommended):
```bash
@@ -283,6 +283,8 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>
> ⚠️ The following three sub-steps MUST be **executed individually one at a time**. Each command must complete and be confirmed successful before running the next.
> ❌ **NEVER** put all three commands in a single code block or single shell invocation.
+Run the canonical three-command pipeline (same as `references/shared-standards.md` §5):
+
**Step 7.1** — Split speaker notes:
```bash
python3 ${SKILL_DIR}/scripts/total_md_split.py <project_path>
@@ -297,8 +299,6 @@ python3 ${SKILL_DIR}/scripts/finalize_svg.py <project_path>
```bash
python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> -s final
# Output: exports/<project_name>_<timestamp>.pptx + exports/<project_name>_<timestamp>_svg.pptx
-# Use --only native to skip SVG reference version
-# Use --only legacy to only generate SVG image version
```
> ❌ **NEVER** use `cp` as a substitute for `finalize_svg.py` — it performs multiple critical processing steps
@@ -327,11 +327,11 @@ Before switching roles, you **MUST first read** the corresponding reference file
| Canvas format specification | `references/canvas-formats.md` |
| Image layout specification | `references/image-layout-spec.md` |
| SVG image embedding | `references/svg-image-embedding.md` |
+| Icon library | `templates/icons/README.md` |
---
## Notes
-- Do NOT add extra flags like `--only` to the post-processing commands — run them as-is
- Local preview: `python3 -m http.server -d <project_path>/svg_final 8000`
- **Troubleshooting**: If the user encounters issues during generation (layout overflow, export errors, blank images, etc.), recommend checking `docs/faq.md` — it contains known solutions sourced from real user reports and is continuously updated
diff --git a/skills/ppt-master/references/executor-base.md b/skills/ppt-master/references/executor-base.md
index 5b6b6345..1ed145a5 100644
--- a/skills/ppt-master/references/executor-base.md
+++ b/skills/ppt-master/references/executor-base.md
@@ -103,7 +103,7 @@ File naming format: `<number>_<page_name>.svg`
## 4. Icon Usage
-Four approaches: **A: Emoji** (`<text>🚀</text>`) | **B: AI-generated** (SVG basic shapes) | **C: Built-in library** (`templates/icons/` 11000+ icons, recommended) | **D: Custom** (user-specified)
+Strategist chooses the icon approach and approved inventory. Executor only implements the approved choice. Built-in library details and the one-library rule are documented in [`../templates/icons/README.md`](../templates/icons/README.md); this section defines the SVG placeholder syntax.
**Built-in icons — Placeholder method (recommended)**:
@@ -134,20 +134,6 @@ Four approaches: **A: Emoji** (`<text>🚀</text>`) | **B: AI-generated** (SVG b
>
> No need to manually run `embed_icons.py`; `finalize_svg.py` post-processing tool will auto-embed icons.
-**Five icon libraries** — four stylistic + one brand-logo:
-
-| Library | Style | Count | Prefix | When to use |
-|---------|-------|-------|--------|-------------|
-| `chunk` | fill · straight-line geometry (sharp corners, rectilinear) | 640 | `chunk/` | ✅ **Default** — most scenarios |
-| `tabler-filled` | fill · bezier-curve forms (smooth, rounded contours) | 1000+ | `tabler-filled/` | When design calls for smooth, rounded, organic icon forms |
-| `tabler-outline` | stroke/line | 5000+ | `tabler-outline/` | Screen-only decks needing a light, elegant aesthetic |
-| `phosphor-duotone` | duotone · single color + 0.2-opacity backplate | 1200+ | `phosphor-duotone/` | Modern SaaS / fintech / product launches — soft depth without solid weight |
-| `simple-icons` | **brand logos** (real company / product marks) | 3400+ | `simple-icons/` | Brand-logo inset — see exception rule below |
-
-> ⚠️ **One presentation = one stylistic library** — pick `chunk` / `tabler-filled` / `tabler-outline` / `phosphor-duotone` and use it exclusively for all generic icons (home, chart, users, etc.). If the chosen library lacks an exact icon, find the closest available alternative within that same library.
->
-> **Brand-logo exception (`simple-icons`)**: `simple-icons` is NOT a stylistic library and does NOT participate in the "one library" rule. Use it **alongside** the chosen stylistic library, but **only** for real company / product / service brand marks (customer logos, tech-stack icons, social handles). Do **not** use `simple-icons` to substitute for a missing icon in the primary library — that's still a violation.
-
**Searching for icons** — use terminal, zero token cost:
```bash
ls skills/ppt-master/templates/icons/chunk/ | grep home
@@ -209,15 +195,16 @@ When the Design Spec includes a **VII. Visualization Reference List**, read the
## 6. Image Handling
-Handle images based on their status in the Design Specification's "Image Resource List":
+Handle images based on their status in the Design Specification's "Image Resource List". Status names and lifecycle are defined in [`svg-image-embedding.md`](svg-image-embedding.md).
| Status | Source | Handling |
|--------|--------|----------|
| **Existing** | User-provided | Reference images directly from `../images/` directory |
-| **AI-generated** | Generated by Image_Generator | Images already in `../images/`, reference directly |
+| **Generated** | Generated by Image_Generator | Reference images directly from `../images/` directory |
+| **Needs-Manual** | Generation failed and file is absent | Use dashed border placeholder unless the expected file exists |
| **Placeholder** | Not yet prepared | Use dashed border placeholder |
-**Reference**: `<image href="../images/xxx.png" ... preserveAspectRatio="xMidYMid slice"/>`
+**Reference syntax**: see [`svg-image-embedding.md`](svg-image-embedding.md).
**Placeholder**: Dashed border `<rect stroke-dasharray="8,4" .../>` + description text
@@ -289,7 +276,7 @@ Automatically split `notes/total.md` into individual speaker note files in the `
> **Auto-continuation**: After Visual Construction Phase (all SVG pages) and Logic Construction Phase (all notes) are complete, the Executor proceeds directly to the post-processing pipeline.
-**Post-processing & Export** (see [shared-standards.md](shared-standards.md)):
+**Post-processing & Export** (same canonical pipeline as [shared-standards.md §5](shared-standards.md)):
```bash
# 1. Split speaker notes
diff --git a/skills/ppt-master/references/image-generator.md b/skills/ppt-master/references/image-generator.md
index cf566d8a..7f1645e7 100644
--- a/skills/ppt-master/references/image-generator.md
+++ b/skills/ppt-master/references/image-generator.md
@@ -28,6 +28,8 @@ Receive the "Image Resource List" from the Design Specification & Content Outlin
|----------|-----------|---------|------|--------|----------------------|
| cover_bg.png | 1920x1080 | Cover background | Background | Pending | Modern tech abstract background, deep blue gradient |
+ Status values are defined in [`svg-image-embedding.md`](svg-image-embedding.md). Image_Generator consumes only `Pending` rows and changes them to `Generated` or `Needs-Manual`.
+
### Output
| Deliverable | Path / Description | Requirements |
@@ -35,7 +37,7 @@ Receive the "Image Resource List" from the Design Specification & Content Outlin
| Prompt document | `project/images/image_prompts.md` | **Must** be saved using file write tool — cannot just be output in conversation |
| Optimized prompts | Individual prompt per image | Directly usable with AI image generation tools; doubles as alt text |
| Image files | `project/images/` directory | Named per the resource list filenames |
-| Updated list | Status changes | `Pending` → `Generated` (success) or `Pending` → `Needs-Manual` (generation attempted and failed) |
+| Updated list | Status changes | `Pending` -> `Generated` (success) or `Pending` -> `Needs-Manual` (generation attempted and failed) |
---
@@ -328,7 +330,7 @@ If the user chooses to generate manually on a platform that watermarks outputs (
- Agent must NOT claim an image is generated without producing an actual file at the expected path
- Agent must NOT mark an image as `Needs-Manual` without a real generation attempt having failed
-- Status transitions are evidence-driven: `Pending` → `Generated` (file exists at expected path) or `Pending` → `Needs-Manual` (generation attempted and failed after one retry)
+- Status transitions are evidence-driven: `Pending` -> `Generated` (file exists at expected path) or `Pending` -> `Needs-Manual` (generation attempted and failed after one retry)
### 4.4 Verification Phase
diff --git a/skills/ppt-master/references/image-layout-spec.md b/skills/ppt-master/references/image-layout-spec.md
index 690810cb..ffb0f8bb 100644
--- a/skills/ppt-master/references/image-layout-spec.md
+++ b/skills/ppt-master/references/image-layout-spec.md
@@ -182,9 +182,22 @@ Image positions:
---
-## SVG Image Embedding Code
+## Handoff Fields
-### Complete Display (recommended for data charts)
+This spec only defines layout calculation. Write the computed layout fields into the Image Resource List defined in [`svg-image-embedding.md`](svg-image-embedding.md):
+
+| Field | Meaning |
+|-------|---------|
+| `Ratio` | Original image width / height |
+| `Layout plan` | Top-bottom / left-right / grid, including split ratio when relevant |
+| `Image area` | Computed display rectangle size |
+| `Text area` | Computed remaining text area size |
+
+For SVG `<image>` syntax, path rules, `preserveAspectRatio`, external references, and Base64 embedding, use [`svg-image-embedding.md`](svg-image-embedding.md).
+
+### SVG Image Embedding Examples
+
+Complete display, recommended for data charts and side-by-side images where content must not be cropped:
```xml
<image href="../images/xxx.png"
@@ -192,7 +205,7 @@ Image positions:
preserveAspectRatio="xMidYMid meet"/>
```
-### Crop-to-Fill (backgrounds only)
+Crop-to-fill, for backgrounds and hero images only:
```xml
<image href="../images/bg.png"
@@ -202,25 +215,6 @@ Image positions:
---
-## Image Resource List Template
-
-In the Design Specification & Content Outline, the image resource list must include:
-
-| Field | Description | Example |
-|-------|-------------|---------|
-| Filename | Image filename | `p12_0.png` |
-| Original dimensions | Width x Height | 1524x968 |
-| Ratio | Width / Height | 1.57 |
-| Page | Usage page number | Page 5 |
-| Type | Visual type | Background / Photography / Illustration / Diagram / Decorative |
-| Layout plan | Top-bottom/Left-right + split ratio | Top-bottom 6:4 or Left-right 7:3 |
-| Image area | Image display dimensions | 1160x420 or 780x446 |
-| Text area | Remaining space dimensions | 1160x200 or 360x600 |
-
-**The Type field is used by Image_Generator to select the appropriate prompt strategy.**
-
----
-
## Automation Tool
```bash
diff --git a/skills/ppt-master/references/strategist.md b/skills/ppt-master/references/strategist.md
index 93f3d756..4ca4a8f4 100644
--- a/skills/ppt-master/references/strategist.md
+++ b/skills/ppt-master/references/strategist.md
@@ -88,15 +88,9 @@ Proactively provide a color scheme (HEX values) based on content characteristics
| **C** | Built-in icon library | Professional scenarios (recommended) |
| **D** | Custom icons | Has brand assets |
-Built-in library contains 11000+ icons across five libraries — four stylistic + one brand-logo:
+The built-in icon library contains multiple stylistic libraries plus a brand-logo library:
-| Library | Style | Count | Prefix | When to use |
-|---------|-------|-------|--------|-------------|
-| `chunk` | fill · straight-line geometry (sharp corners, rectilinear) | 640 | `chunk/` | Sharp, structured, engineered feel |
-| `tabler-filled` | fill · bezier-curve forms (smooth, rounded contours) | 1000+ | `tabler-filled/` | Warm, rounded, organic feel |
-| `tabler-outline` | stroke/line | 5000+ | `tabler-outline/` | Light, elegant, screen-only aesthetic |
-| `phosphor-duotone` | duotone · single color + 0.2-opacity backplate | 1200+ | `phosphor-duotone/` | Soft depth without solid weight — modern SaaS / fintech / product launches |
-| `simple-icons` | **brand logos** (real company / product marks) | 3400+ | `simple-icons/` | Brand-logo inset — coexists with the chosen stylistic library, never replaces it |
+See [`../templates/icons/README.md`](../templates/icons/README.md) for the current library inventory, counts, prefixes, and SVG placeholder details.
> **Mandatory rules when choosing C**:
> 1. **Pick exactly one stylistic library based on content tone** (reference mappings — not hard rules):
@@ -209,7 +203,7 @@ Selection principle: Baseline choice is driven by **content density**, not desig
| Layout suggestion | e.g., `Wide landscape (suitable for full-screen/illustration)` |
| Purpose | e.g., `Cover background` |
| Type | Background / Photography / Illustration / Diagram / Decorative pattern |
-| Status | Pending generation / Existing / Placeholder |
+| Status | Initial status must be `Pending`, `Existing`, or `Placeholder`; see [`svg-image-embedding.md`](svg-image-embedding.md) for the full status enum |
| Generation description | Fill in detailed description for AI generation |
**Generation description quality guide** — the description is the seed for Image_Generator's prompt, so specificity matters:
@@ -260,7 +254,7 @@ Core logic (side-by-side only): the container's aspect ratio must closely match
> **Multi-image slides**: When multiple images appear on one page, use the grid formulas in the "Multi-Image Layout" section of `references/image-layout-spec.md`.
-> **Pipeline handoff**: When C) AI generation is selected, after outputting the design spec, prompt the user to invoke Image_Generator. Once images are collected in `images/`, proceed to Executor.
+> **Pipeline handoff**: When C) AI generation is selected, Image_Generator consumes `Pending` rows and updates them to `Generated` or `Needs-Manual` before Executor proceeds. Status names are defined in [`svg-image-embedding.md`](svg-image-embedding.md).
### Visualization Reference (Non-blocking — Strategist recommends, no user confirmation needed)
diff --git a/skills/ppt-master/references/svg-image-embedding.md b/skills/ppt-master/references/svg-image-embedding.md
index 80c55f45..78b33f50 100644
--- a/skills/ppt-master/references/svg-image-embedding.md
+++ b/skills/ppt-master/references/svg-image-embedding.md
@@ -8,23 +8,25 @@ Technical specifications and recommended workflow for adding images to SVG files
## Image Resource List Format
-Defined in the Design Specification & Content Outline; each image has a status annotation. If the image approach includes "B) User-provided", you must run `analyze_images.py` immediately after the Strategist completes the Eight Confirmations, and complete the list before outputting the design spec.
+Defined in the Design Specification & Content Outline; each image has a status annotation. This file is the authority for image status names and SVG image embedding behavior. If the image approach includes "B) User-provided", run `analyze_images.py` immediately after the Strategist completes the Eight Confirmations, and complete the list before outputting the design spec.
```markdown
-| Filename | Dimensions | Purpose | Status | Generation Description |
-|----------|-----------|---------|--------|----------------------|
-| cover_bg.png | 1280x720 | Cover background | Pending | Modern tech abstract background, deep blue gradient |
-| product.png | 600x400 | Page 3 | Existing | - |
-| team.png | 600x400 | Page 5 | Placeholder | Team collaboration scene (to be added later) |
+| Filename | Dimensions | Purpose | Type | Status | Generation Description |
+|----------|------------|---------|------|--------|------------------------|
+| cover_bg.png | 1280x720 | Cover background | Background | Pending | Modern tech abstract background, deep blue gradient |
+| product.png | 600x400 | Page 3 product photo | Photography | Existing | - |
+| team.png | 600x400 | Page 5 team scene | Illustration | Placeholder | Team collaboration scene to be added later |
```
-### Three Status Types
+### Image Status Enum
| Status | Meaning | Executor Handling |
|--------|---------|-------------------|
-| **Pending** | Needs AI generation, has description | Generate image first into `images/`, then reference with `<image>` |
+| **Pending** | Needs AI generation, has a generation description | Image_Generator must attempt generation before Executor; should not remain in the list after Step 5 |
+| **Generated** | AI-generated file exists at the expected path | Reference directly from `../images/` |
+| **Needs-Manual** | Generation was attempted once plus one retry and failed | Use a dashed placeholder unless the user has manually supplied the expected file |
| **Existing** | User already has image | Place in `images/`, reference with `<image>` |
-| **Placeholder** | Not yet processed | Use dashed border placeholder; replace later |
+| **Placeholder** | Image intentionally not prepared yet | Use dashed border placeholder; replace later |
---
@@ -32,14 +34,12 @@ Defined in the Design Specification & Content Outline; each image has a status a
```
1. Strategist defines image needs → Add image resource list, annotate each status
-2. Image preparation (pending/existing) → Place in project/images/
+2. Image preparation (Pending / Existing) → Place available files in project/images/
3. Executor generates SVGs (svg_output/)
- ├── Existing/Pending → <image href="../images/xxx.png" .../>
- └── Placeholder → Dashed border + description text
+ ├── Existing / Generated → <image href="../images/xxx.png" .../>
+ └── Placeholder / Needs-Manual without file → Dashed border + description text
4. Preview: python3 -m http.server -d <project_path> 8000 → /svg_output/<filename>.svg
-5. Post-processing & Export
- ├── python3 scripts/finalize_svg.py <project_path>
- └── python3 scripts/svg_to_pptx.py <project_path> -s final
+5. Post-processing & Export → follow shared-standards.md §5
```
> Recommended: During generation, keep external references in `svg_output/`. Post-processing via `finalize_svg.py` auto-embeds images into `svg_final/`, then export PPTX from `svg_final/`.
@@ -114,11 +114,11 @@ python3 -m http.server -d <project_path> 8000
## Conversion Process
-### Recommended: Use finalize_svg.py (Unified Pipeline)
+Use the unified post-processing pipeline in [shared-standards.md §5](shared-standards.md). It runs `finalize_svg.py` before export so image references from `svg_output/` become embedded assets in `svg_final/`.
```bash
-python3 scripts/finalize_svg.py <project_path> # Icons, images, text, rounded rects — all in one pass
-python3 scripts/svg_to_pptx.py <project_path> -s final # Export PPTX from final version
+python3 scripts/finalize_svg.py <project_path>
+python3 scripts/svg_to_pptx.py <project_path> -s final
```
### Standalone: embed_images.py (Advanced Usage)
@@ -157,14 +157,9 @@ project/
### Rounded Corner / Non-rectangular Image Cropping
-`clipPath` **on `<image>` elements** is conditionally allowed — the converter maps qualifying clip shapes to native DrawingML picture geometry (`<a:prstGeom>` / `<a:custGeom>`), so rounded corners, circular avatars, hexagonal portraits, etc. are fully supported end-to-end.
+`clipPath` **on `<image>` elements** is conditionally allowed. The authoritative constraints are in [shared-standards.md §1.2](shared-standards.md); do not restate or relax them here.
-Constraints (see [shared-standards.md §1.2](shared-standards.md) for the authoritative list):
-- The `<clipPath>` must live inside `<defs>` and contain exactly **one** shape child — `circle`, `ellipse`, `rect` with `rx`/`ry`, `path`, or `polygon`.
-- `clip-path` may appear **only** on `<image>` elements. Using it on shapes / groups / text is an error — draw the target geometry directly with the matching native element (`<circle>` / `<ellipse>` / `<rect rx="...">` / `<polygon>` / `<path>`). A rect clipped to a circle is just a `<circle>`.
-- PowerPoint's own SVG renderer does not render `clipPath` correctly. The Native PPTX converter handles it, but the SVG reference version in the `_svg.pptx` backup will display the image uncropped.
-
-Alternative for the rare case where `clipPath` does not fit (e.g. shape needs clipping): bake the rounded corners into the source image (PNG with alpha) before embedding.
+Alternative for the rare case where `clipPath` does not fit: bake the rounded corners into the source image (PNG with alpha) before embedding.
---