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(SKILL): tighten prose, keep all rules and concrete values
hugohe30f2bbdfe2112
diff --git a/skills/ppt-master/SKILL.md b/skills/ppt-master/SKILL.mdindex 61ab1d39..5d7edba0 100644--- a/skills/ppt-master/SKILL.md+++ b/skills/ppt-master/SKILL.md@@ -30,16 +30,15 @@ description: >> [!IMPORTANT]> ## 🌐 Language & Communication Rule>-> - **Response language**: Always match the language of the user's input and provided source materials. For example, if the user asks in Chinese, respond in Chinese; if the source material is in English, respond in English.-> - **Explicit override**: If the user explicitly requests a specific language (e.g., "请用英文回答" or "Reply in Chinese"), use that language instead.-> - **Template format**: The `design_spec.md` file MUST always follow its original English template structure (section headings, field names), regardless of the conversation language. Content values within the template may be in the user's language.+> - **Response language**: match the user's input and source materials. Explicit user override (e.g., "请用英文回答") takes precedence.+> - **Template format**: `design_spec.md` MUST follow its original English template structure (section headings, field names) regardless of conversation language. Content values may be in the user's language.> [!IMPORTANT]> ## 🔌 Compatibility With Generic Coding Skills>-> - `ppt-master` is a repository-specific workflow skill, not a general application scaffold-> - Do NOT create or require `.worktrees/`, `tests/`, branch workflows, or other generic engineering structure by default-> - If another generic coding skill suggests repository conventions that conflict with this workflow, follow this skill first unless the user explicitly asks otherwise+> - `ppt-master` is a repository-specific workflow, not a general application scaffold+> - Do NOT create `.worktrees/`, `tests/`, branch workflows, or generic engineering structure by default+> - On conflict with a generic coding skill, follow this skill unless the user explicitly says otherwise## Main Pipeline Scripts@@ -119,10 +118,7 @@ Import source content (choose based on the situation):| Has source files (PDF/MD/etc.) | `python3 ${SKILL_DIR}/scripts/project_manager.py import-sources <project_path> <source_files...> --move` || User provided text directly in conversation | No import needed — content is already in conversation context; subsequent steps can reference it directly |-> ⚠️ **MUST use `--move`**: All source files (original PDF / MD / images) MUST be **moved** (not copied) into `sources/` for archiving.-> - Markdown files generated in Step 1, original PDFs, original MDs — **all** must be moved into the project via `import-sources --move`-> - Intermediate artifacts (e.g., `_files/` directories) are handled automatically by `import-sources`-> - After execution, source files no longer exist at their original location+> ⚠️ **MUST use `--move`** (not copy): all source files — Step 1's generated Markdown, original PDFs / MDs / images — go into `sources/` via `import-sources --move`. After execution they no longer exist at the original location. Intermediate artifacts (e.g., `_files/`) are handled automatically.**✅ Checkpoint — Confirm project structure created successfully, `sources/` contains all source files, converted materials are ready. Proceed to Step 3.**@@ -132,15 +128,15 @@ Import source content (choose based on the situation):🚧 **GATE**: Step 2 complete; project directory structure is ready.-**Default path — free design, no question asked.** Proceed directly to Step 4. Do NOT query `layouts_index.json` and do NOT ask the user an A/B template-vs-free-design question. Free design is the standard mode: the AI tailors structure and style to the specific content.+**Default — free design.** Proceed directly to Step 4. Do NOT query `layouts_index.json`. Do NOT ask the user an A/B template-vs-free-design question.-**Template flow is opt-in.** Enter it only when one of these explicit triggers appears in the user's prior messages:+**Template flow is opt-in.** Enter it only when an explicit trigger appears in the user's prior messages:-1. User names a specific template (e.g., "用 mckinsey 模板" / "use the academic_defense template")-2. User names a style / brand reference that maps to a template (e.g., "McKinsey 那种" / "Google style" / "学术答辩样式")-3. User explicitly asks what templates exist (e.g., "有哪些模板可以用")+1. Names a specific template (e.g., "用 mckinsey 模板" / "use the academic_defense template")+2. Names a style / brand reference that maps to a template (e.g., "McKinsey 那种" / "Google style" / "学术答辩样式")+3. Asks what templates exist (e.g., "有哪些模板可以用")-Only when a trigger fires: read `${SKILL_DIR}/templates/layouts/layouts_index.json`, resolve the match (or list available options for trigger 3), and copy template files to the project directory:+When triggered: read `${SKILL_DIR}/templates/layouts/layouts_index.json`, resolve the match (or list options for trigger 3), and copy:```bashcp ${SKILL_DIR}/templates/layouts/<template_name>/*.svg <project_path>/templates/@@ -149,11 +145,11 @@ cp ${SKILL_DIR}/templates/layouts/<template_name>/*.png <project_path>/images/ 2cp ${SKILL_DIR}/templates/layouts/<template_name>/*.jpg <project_path>/images/ 2>/dev/null || true```-**Soft hint (non-blocking, optional).** Before Step 4, if the user's content is an obvious strong match for an existing template (e.g., clearly an academic defense, a government report, a McKinsey-style consulting deck) AND the user has given no template signal, the AI MAY emit a single-sentence notice and continue without waiting:+**Soft hint (non-blocking).** When content is an obvious strong match for an existing template (e.g., academic defense, government report, McKinsey-style deck) AND no template trigger fired, emit a single-sentence notice and continue without waiting:> Note: the library has a template `<name>` that matches this scenario closely. Say the word if you want to use it; otherwise I'll continue with free design.-This is a hint, not a question — do NOT block, do NOT require an answer. Skip the hint entirely when the match is weak or ambiguous.+Hint, not question — do NOT block. Skip entirely on weak/ambiguous match.> To create a new global template, read `workflows/create-template.md`@@ -170,11 +166,11 @@ First, read the role definition:Read references/strategist.md```-> ⚠️ **Mandatory gate in `strategist.md`**: Before writing `design_spec.md`, Strategist MUST `read_file templates/design_spec_reference.md` and produce the spec following its full I–XI section structure. See `strategist.md` Section 1 for the explicit gate rule.+> ⚠️ **Mandatory gate**: before writing `design_spec.md`, Strategist MUST `read_file templates/design_spec_reference.md` and follow its full I–XI section structure. See `strategist.md` Section 1.-**Must complete the Eight Confirmations** (full template structure in `templates/design_spec_reference.md`):+**Eight Confirmations** (full template: `templates/design_spec_reference.md`):-⛔ **BLOCKING**: The Eight Confirmations MUST be presented to the user as a bundled set of recommendations, and you MUST **wait for the user to confirm or modify** before outputting the Design Specification & Content Outline. This is the single core confirmation point in the workflow. Once confirmed, all subsequent script execution and slide generation should proceed fully automatically.+⛔ **BLOCKING**: present the Eight Confirmations as a bundled recommendation set and **wait for explicit user confirmation or modification** before outputting Design Specification & Content Outline. This is the single core confirmation point — once confirmed, all subsequent steps proceed automatically.1. Canvas format2. Page count range@@ -185,16 +181,16 @@ Read references/strategist.md7. Typography plan8. Image usage approach-If the user has provided images, run the analysis script **before outputting the design spec** (do NOT directly read/open image files — use the script output only):+If the user provided images, run analysis **before outputting the design spec**:```bashpython3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images```-> ⚠️ **Image handling rule**: The AI must NEVER directly read, open, or view image files (`.jpg`, `.png`, etc.). All image information must come from the `analyze_images.py` script output or the Design Specification's Image Resource List.+> ⚠️ **Image handling**: NEVER directly read / open / view image files (`.jpg`, `.png`, etc.). All image info comes from `analyze_images.py` output or the Design Spec's Image Resource List.**Output**:- `<project_path>/design_spec.md` — human-readable design narrative-- `<project_path>/spec_lock.md` — machine-readable execution contract (distilled from the decisions in design_spec.md; Executor re-reads this before every page). See `templates/spec_lock_reference.md` for the skeleton.+- `<project_path>/spec_lock.md` — machine-readable execution contract (skeleton: `templates/spec_lock_reference.md`); Executor re-reads before every page**✅ Checkpoint — Phase deliverables complete, auto-proceed to next step**:```markdown@@ -211,7 +207,7 @@ python3 ${SKILL_DIR}/scripts/analyze_images.py <project_path>/images🚧 **GATE**: Step 4 complete; Design Specification & Content Outline generated and user confirmed.-> **Trigger condition**: Image approach includes "AI generation". If not triggered, skip directly to Step 6 (Step 6 GATE must still be satisfied).+> **Trigger**: Image approach includes "AI generation". Otherwise skip to Step 6.Read `references/image-generator.md`@@ -247,25 +243,24 @@ Read references/executor-consultant.md # Consulting styleRead references/executor-consultant-top.md # Top consulting style (MBB level)```-> Only need to read executor-base + shared-standards + one style file.+> Only read executor-base + shared-standards + one style file.-**Design Parameter Confirmation (Mandatory)**: Before generating the first SVG, the Executor MUST review and output key design parameters from the Design Specification (canvas dimensions, color scheme, font plan, body font size) to ensure spec adherence. See executor-base.md Section 2 for details.+**Design Parameter Confirmation (Mandatory)**: before the first SVG, output key design parameters from the spec (canvas dimensions, color scheme, font plan, body font size). See executor-base.md §2.-**Per-page spec_lock re-read (Mandatory)**: Before generating **each** SVG page, Executor MUST `read_file <project_path>/spec_lock.md` and use only the colors / fonts / icons / images listed there. This resists context-compression drift on long decks. See executor-base.md §2.1 for details.+**Per-page spec_lock re-read (Mandatory)**: before **each** SVG page, `read_file <project_path>/spec_lock.md` and use only its colors / fonts / icons / images. Resists context-compression drift on long decks. See executor-base.md §2.1.-> ⚠️ **Main-agent only rule**: SVG generation in Step 6 MUST remain with the current main agent because page design depends on full upstream context (source content, design spec, template mapping, image decisions, and cross-page consistency). Do NOT delegate any slide SVG generation to sub-agents.-> ⚠️ **Generation rhythm rule**: After confirming the global design parameters, the Executor MUST generate pages sequentially, one page at a time, while staying in the same continuous main-agent context. Do NOT split Step 6 into grouped page batches such as 5 pages per batch.+> ⚠️ **Main-agent only**: SVG generation MUST stay in the current main agent — page design depends on full upstream context. Do NOT delegate to sub-agents.+> ⚠️ **Generation rhythm**: generate pages sequentially, one at a time, in the same continuous context. Do NOT batch (e.g., 5 per group).-**Visual Construction Phase**:-- Generate SVG pages sequentially, one page at a time, in one continuous pass → `<project_path>/svg_output/`+**Visual Construction Phase**: generate SVG pages sequentially, one at a time, in one continuous pass → `<project_path>/svg_output/`-**Quality Check Gate (Mandatory)** — after all SVGs are generated and BEFORE speaker notes:+**Quality Check Gate (Mandatory)** — after all SVGs, BEFORE speaker notes:```bashpython3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>```-- Any `error` (banned SVG features, viewBox mismatch, spec_lock drift, etc.) MUST be fixed on the offending page before proceeding — go back to Visual Construction, re-generate that page, re-run the check.-- `warning` entries (e.g., low-resolution image, non-PPT-safe font tail) should be reviewed and fixed when straightforward; may be acknowledged and released otherwise.-- Running the checker against `svg_output/` is required — running it only after `finalize_svg.py` is too late (finalize rewrites SVG and some violations get masked).+- Any `error` (banned SVG features, viewBox mismatch, spec_lock drift, etc.) MUST be fixed before proceeding — return to Visual Construction, regenerate that page, re-run check.+- `warning` entries (low-res image, non-PPT-safe font tail, etc.): fix when straightforward, otherwise acknowledge and release.+- Run against `svg_output/` (not after `finalize_svg.py` — finalize rewrites SVG and masks violations).**Chart Coordinate Calibration (Mandatory)** — after quality check passes, BEFORE Logic Construction:@@ -278,8 +273,7 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>> AI models routinely introduce 10-50 px coordinate errors. Do NOT skip.-**Logic Construction Phase**:-- Generate speaker notes → `<project_path>/notes/total.md`+**Logic Construction Phase**: generate speaker notes → `<project_path>/notes/total.md`**✅ Checkpoint — Confirm all SVGs and notes are fully generated and quality-checked. Proceed directly to Step 7 post-processing**:```markdown@@ -296,10 +290,10 @@ python3 ${SKILL_DIR}/scripts/svg_quality_checker.py <project_path>🚧 **GATE**: Step 6 complete; all SVGs generated to `svg_output/`; speaker notes `notes/total.md` generated.-> ⚠️ 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 three sub-steps **one at a time** — each must complete successfully before the next.+> ❌ **NEVER** combine them into a single code block or shell invocation.-Run the canonical three-command pipeline (same as `references/shared-standards.md` §5):+Canonical three-command pipeline (mirrors `references/shared-standards.md` §5):**Step 7.1** — Split speaker notes:```bash@@ -317,15 +311,15 @@ python3 ${SKILL_DIR}/scripts/svg_to_pptx.py <project_path> -s final# Output: exports/<project_name>_<timestamp>.pptx + exports/<project_name>_<timestamp>_svg.pptx```-> ❌ **NEVER** use `cp` as a substitute for `finalize_svg.py` — it performs multiple critical processing steps-> ❌ **NEVER** export directly from `svg_output/` — MUST use `-s final` to export from `svg_final/`+> ❌ **NEVER** substitute `cp` for `finalize_svg.py` — finalize performs multiple critical processing steps+> ❌ **NEVER** export from `svg_output/` — MUST use `-s final` (exports from `svg_final/`)> ❌ **NEVER** add extra flags like `--only`---## Role Switching Protocol-Before switching roles, you **MUST first read** the corresponding reference file — skipping is FORBIDDEN. Output marker:+Before switching roles, **MUST first read** the corresponding reference file. Output marker:```markdown## [Role Switch: <Role Name>]@@ -350,4 +344,4 @@ Before switching roles, you **MUST first read** the corresponding reference file## Notes- 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+- **Troubleshooting**: on generation issues (layout overflow, export errors, blank images, etc.), check `docs/faq.md` for known solutions