| 1 | # FAQ |
| 2 | |
| 3 | [English](./faq.md) | [Chinese](./zh/faq.md) |
| 4 | |
| 5 | --- |
| 6 | |
| 7 | ## Q: What source formats does PPT Master accept? |
| 8 | |
| 9 | Almost anything: **PDF**, **DOCX**, **PPTX**, **EPUB**, **HTML**, **LaTeX**, **RST**, **URLs** (including WeChat articles), **Markdown**, or just plain text pasted into the conversation. The AI agent converts your source material to Markdown automatically before generating slides. |
| 10 | |
| 11 | ## Q: Can I generate a deck with just a topic, no source materials? |
| 12 | |
| 13 | Yes. Tell the AI your topic or scenario (e.g. "make a PPT about Hayao Miyazaki", "introduce our new product"). The Generate PPTX route will run its **topic-research stage** to gather the factual baseline and provenance needed for planning. If you provide partial material, the same stage may fill only the factual gaps required by your requested outcome unless you ask for a source-only result. Images are selected during Strategist planning and acquired only after final confirmation. |
| 14 | |
| 15 | Quality depends on what's on the open web. If you already have specialized material (papers, internal docs), giving those files to the AI directly produces better results than web research alone. |
| 16 | |
| 17 | ## Q: Can PPT Master produce formats other than PowerPoint? |
| 18 | |
| 19 | Yes. Besides the standard **16:9** and **4:3** presentation formats, PPT Master supports social media and marketing formats out of the box: |
| 20 | |
| 21 | | Format | Use Case | |
| 22 | |--------|----------| |
| 23 | | Xiaohongshu (RED) 3:4 | Image-text sharing, knowledge posts | |
| 24 | | WeChat Moments / IG 1:1 | Square posters, brand showcases | |
| 25 | | Story / TikTok 9:16 | Vertical stories, short video covers | |
| 26 | | WeChat Article Header | WeChat article cover images | |
| 27 | | A4 Print | Print posters, flyers | |
| 28 | |
| 29 | Just specify the format when starting a project (e.g., `--format xhs`). The output is still a `.pptx` file containing native shapes. |
| 30 | |
| 31 | ## Q: What AI tools work with PPT Master? |
| 32 | |
| 33 | PPT Master works inside any agent-capable AI tool that can read files and run shell commands — **Claude Code** (CLI / VS Code / JetBrains / Web), **VS Code Copilot**, **Codex**, and others. See the cost comparison below for pricing differences. |
| 34 | |
| 35 | ## Q: I downloaded an old version. How do I update to the latest? |
| 36 | |
| 37 | It depends on how you installed PPT Master: |
| 38 | |
| 39 | | Install method | Update method | |
| 40 | |---|---| |
| 41 | | Git clone | Run `python3 skills/ppt-master/scripts/update_repo.py` inside the `ppt-master` folder | |
| 42 | | Download ZIP | Download the latest ZIP, unzip it into a new folder, copy your old `.env` and `projects/` folder into the new folder, then run `pip install -r requirements.txt` | |
| 43 | | Skill marketplace | Reinstall or update through the matching marketplace / skills tool | |
| 44 | |
| 45 | For long-term use, Git clone is recommended. ZIP is fine for a quick trial, but it has no Git history and cannot run `git pull`. |
| 46 | |
| 47 | If you are not sure which install method you used, ask the AI to run this from the project folder: |
| 48 | |
| 49 | ```bash |
| 50 | python3 skills/ppt-master/scripts/update_repo.py |
| 51 | ``` |
| 52 | |
| 53 | If the folder is not a Git clone, the script will tell you how to migrate a ZIP install. |
| 54 | |
| 55 | ## Q: The repo is over 1 GB and my skills tool fails to download it — can I get just the skill? |
| 56 | |
| 57 | Yes. The full repository is large (Git history plus bundled example decks and their assets), and that size is baked into the history — it can't be trimmed without breaking the many existing forks. If you only want the skill and not the full repo, use a lightweight path instead: |
| 58 | |
| 59 | - **Marketplace CLI**: `npx skills add hugohe3/ppt-master` or Claude Code's `/plugin install` fetch the skill files only (see the Set Up section of the README). |
| 60 | - **Manual download**: grab `ppt-master-skill-*.zip` from the [Releases](https://github.com/hugohe3/ppt-master/releases) page — the skill files only (~50 MB), no full-repo clone. |
| 61 | |
| 62 | Either way, run `pip install -r requirements.txt` from the installed location so the post-processing scripts work. |
| 63 | |
| 64 | Neither path carries a `.git` directory, so `git describe` cannot report the version. The installed release is recorded in the `metadata.version` field of the skill's own `SKILL.md` frontmatter. |
| 65 | |
| 66 | ## Q: Can I use AI-generated images in my presentation? |
| 67 | |
| 68 | Yes. PPT Master includes a built-in image generation script that supports multiple providers (Gemini, OpenAI, FLUX, Qwen, Zhipu, etc.). During the Strategist phase, if you choose "AI generation" for the image approach, the pipeline will automatically generate images based on your content. You can also provide your own images — just place them in the project's `images/` folder. |
| 69 | |
| 70 | ## Q: I don't have an image-generation API key — can I still get images? |
| 71 | |
| 72 | Yes — pick "Web-sourced" in the Strategist's Image Usage step. PPT Master ships a zero-config `image_search.py` that searches openly-licensed images across Openverse and Wikimedia Commons (no API key needed). Zero-config search is a fallback: it works immediately, but quality can be uneven because many results are ordinary user uploads. |
| 73 | |
| 74 | For better contemporary stock photography, set `PEXELS_API_KEY` and/or `PIXABAY_API_KEY` in `.env` (both are free). The search will include Pexels / Pixabay automatically, which usually improves people, workplace, lifestyle, product, and illustration images. You can mix paths in one deck (e.g. AI for hero illustrations, web for team photos). If a selected image requires attribution, Executor adds a small inline credit on the affected slide. |
| 75 | |
| 76 | Be clear on what this buys you: **web search only finds *a* relevant, downloadable, license-clean image — it does not guarantee the image is good or right for that page**, because ranking sees text metadata, not the picture. During generation a multimodal model reads a thumbnail to sanity-check and re-queries a poor fit, but **the most reliable route to high quality is to search yourself**: find a better image anywhere, hand the AI its URL, and it downloads and swaps it in via `image_search.py --from-url <url>` (recorded as a manual source; rights are yours to verify). Replacement can happen any time — mid-generation or from live preview — without stopping the run. In short: treat web search as a placeholder fallback and manual picking as the polish step. |
| 77 | |
| 78 | ## Q: Can I edit the generated presentations? |
| 79 | |
| 80 | Yes. The only PPTX converter in the SVG pipeline is PPT Master's own `svg_output/` → DrawingML conversion. It saves a timestamped native PowerPoint deck to `exports/`, with text, graphics, and colors directly editable as PowerPoint objects. With the default output path, both Default Generate and Quick Generate copy the authored `svg_output/` to `backup/<timestamp>/svg_output/`, so the same authored deck can be re-exported without re-running the LLM. For Quick this is package reconstruction, not a recoverable record of the AI's design decisions. |
| 81 | |
| 82 | `finalize_svg.py` remains a mandatory Step 7 operation in the default Generate flow even though native PPTX export reads `svg_output/`. It produces self-contained files in `svg_final/` for visual inspection and for manual insertion into another deck as SVG pictures. The explicit quick-generate profile skips this preview artifact, but still retains the normal postflight report and default-path backup after its lockless final quality check. PowerPoint's manual **Convert to Shape** command is not a supported round-trip path; use the generated native PPTX when you need editable shapes. |
| 83 | |
| 84 | ## Q: How does multiline text export? Can PowerPoint reflow it? |
| 85 | |
| 86 | By default, a mergeable multiline block exports as one editable PowerPoint text frame. Authored line breaks are retained and PowerPoint automatic wrapping is disabled, so resizing the frame does not rewrite the authored line layout. An ordinary generated frame uses PowerPoint's native **Resize shape to fit text** behavior: deleting a retained break expands the frame instead of leaving text outside it. Imported exact frames and structured multiline placeholder carriers retain their fixed-size behavior. |
| 87 | |
| 88 | To let PowerPoint reflow eligible body text, use `--reflow-text`: |
| 89 | |
| 90 | ```bash |
| 91 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --reflow-text |
| 92 | ``` |
| 93 | |
| 94 | This restores automatic paragraph reflow and may change the line count. The legacy `--merge-paragraphs` flag is a compatibility alias for `--reflow-text`. |
| 95 | |
| 96 | Use `--no-merge` only when every visual line must be an independent PowerPoint text frame: |
| 97 | |
| 98 | ```bash |
| 99 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project_path> --no-merge |
| 100 | ``` |
| 101 | |
| 102 | That mode preserves independent per-line object placement, but a 12-line paragraph becomes 12 textboxes. When chatting with the AI, ask for "automatic text reflow" or "one independent text box per visual line" to select the corresponding export mode. |
| 103 | |
| 104 | ## Q: Why are font sizes in px, not pt? Do they change on export? |
| 105 | |
| 106 | PPT Master works in **unitless px end-to-end** — the confirm page, `spec_lock.md`, and the SVG all carry px; there is no pt layer. The SVG canvas is literally 1280×720 px, so px is the real layout / execution unit, and keeping a single unit avoids the size drift you get when a value is "confirmed as 20pt" but written into the SVG as a different number. |
| 107 | |
| 108 | PowerPoint displays pt, so the **export** converts px → pt automatically (`pt = px × 0.75`, kept to one decimal). For example a `24px` body becomes `18pt`, a `42px` title becomes `31.5pt`. So a non-integer like `13.5pt` or `31.5pt` in PowerPoint is **expected and intentional**, not a bug — the size is whatever the px works out to, no longer forced onto whole or half-point values. |
| 109 | |
| 110 | The body baseline is a fixed value per **reading mode** (not a range). This controls reading distance and density; it is separate from the open-ended communication intent: |
| 111 | |
| 112 | | Reading mode | Body px | ≈ exported pt | |
| 113 | |---|---|---| |
| 114 | | `text` (read-close: report / leave-behind) | 20px | 15pt | |
| 115 | | `balanced` (default: roadshow / review) | 24px | 18pt | |
| 116 | | `presentation` (projected / launch) | 32px | 24pt | |
| 117 | |
| 118 | Title, subtitle, footnote and the other roles derive from the body by ratio and snap to clean even px. You can override any role's px value on the confirm page. |
| 119 | |
| 120 | ## Q: How does PPT Master decide a deck's style? |
| 121 | |
| 122 | Two independent choices, locked at confirmation `d`: |
| 123 | |
| 124 | - **Mode** (how the deck argues): `pyramid` / `narrative` / `instructional` / `showcase` / `briefing` — see `references/modes/` |
| 125 | - **Visual style** (how it looks): `swiss-minimal` / `editorial` / `soft-rounded` / `dark-tech` … + `custom` — see `references/visual-styles/` |
| 126 | |
| 127 | Any mode pairs with any visual style. |
| 128 | |
| 129 | ## Q: Is PPT Master expensive to use? |
| 130 | |
| 131 | PPT Master itself is free and open source. The only cost is your own AI model usage. |
| 132 | |
| 133 | AI tools across the industry are shifting to usage-based billing — you pay for what you actually consume. PPT Master works with this model naturally: there's no separate PPT subscription, no proprietary credits, no per-seat fee for a presentation platform on top of what you're already paying for AI. |
| 134 | |
| 135 | And because it runs inside a coding agent, a flat subscription plan lets you make many decks at no extra per-deck cost, while a direct per-token API is simply a different price structure — the choice is yours. Either way, PPT Master adds no cost of its own on top of your AI spend. |
| 136 | |
| 137 | ## Q: Are the charts in the generated PPTX editable? |
| 138 | |
| 139 | By default, charts are rendered as **custom-designed SVG graphics** converted to native PowerPoint shapes — fully editable as shapes (move, recolor, retype, restyle). This is a deliberate default over Excel-driven chart objects: PowerPoint's default charts look generic and dated, and lock decks into rigid templates. SVG charts give you publication-quality visuals you can fine-tune directly in PowerPoint, and they render pixel-consistently across PowerPoint / Keynote / LibreOffice / WPS. |
| 140 | |
| 141 | If your workflow specifically requires Excel-driven data editing or PowerPoint's chart/table-specific controls, export with `--native-charts-and-tables`: supported data charts and pure text-grid tables then ship as **PowerPoint-native Chart / Table objects backed by data** (saved as `exports/<name>_<timestamp>_native_charts_tables.pptx`, keeping the deck's own colors instead of PowerPoint's default theme). The default SVG fallback also becomes editable DrawingML shapes, but it has no chart data workbook or table/chart object model. Native objects may look slightly different across PowerPoint / Keynote / LibreOffice / WPS, so the shape-based route remains the visual-stability default. |
| 142 | |
| 143 | ## Q: Can I change page transitions and element animations? |
| 144 | |
| 145 | Yes. Page transitions are on by default (`fade` 0.4s); per-element object |
| 146 | animation is **off by default**—a page appears as a whole instead of having |
| 147 | elements auto-cascade in one by one. Both are controlled by `svg_to_pptx.py` |
| 148 | flags: `-t/--transition` for page-level and `-a/--animation` for element-level. |
| 149 | The object registry includes entrance, emphasis, motion-path, and exit effects. |
| 150 | |
| 151 | ```bash |
| 152 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t push # different transition |
| 153 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -t none # disable transitions |
| 154 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto # enable per-element entrance (effect mapped from group id) |
| 155 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation entrance_fade # enable with one canonical effect |
| 156 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> --animation emphasis_spin # native emphasis |
| 157 | python3 skills/ppt-master/scripts/pptx_animations.py --list # complete categorized effect list |
| 158 | python3 skills/ppt-master/scripts/svg_to_pptx.py <project> -a auto --animation-trigger on-click # presenter-paced reveals |
| 159 | ``` |
| 160 | |
| 161 | `on-click` is for live presentations. Narrated/video export via `--recorded-narration` rejects it because PPT Master writes page timings, not object-level click timings; use `after-previous` or `with-previous` for narrated decks. |
| 162 | |
| 163 | For common commands, Start-mode guidance, and object-level customization, see [Animations & Transitions](./animations.md). Exact effect and validation behavior remains in the linked execution reference. |
| 164 | |
| 165 | ## Q: Which AI model works best? |
| 166 | |
| 167 | **Claude** (Opus / Sonnet) is the recommended and most tested model. SVG layout requires precise absolute-coordinate calculations (font size x character count x container width), and Claude handles this significantly better than alternatives. |
| 168 | |
| 169 | **GPT series** older versions tended to produce more layout issues — text overflowing containers, misaligned elements, coordinate miscalculations. Newer versions (e.g. GPT-5.5) have improved noticeably and are usable in practice; if issues appear, tell the AI which page to fix. |
| 170 | |
| 171 | Other models (Gemini, GLM, MiniMax, etc.) vary in quality. In general, models with stronger frontend/visual capabilities produce better results. |
| 172 | |
| 173 | ## Q: Someone said PPT Master is "just a toy" — is that fair? |
| 174 | |
| 175 | No. PPT Master is a presentation workflow, not a model or a complete agent. It supplies presentation-specific reasoning, contracts, project state, deterministic conversion, and quality gates; the selected model still sets the quality ceiling. Evaluating the workflow with a weak or small-context model is like test-driving a sports car in first gear and concluding it is slow. |
| 176 | |
| 177 | **The full-power combination:** |
| 178 | |
| 179 | - **Claude with a large context window** (ideally ~1M tokens): a large context window lets the Executor see every previously generated page in the same session, maintaining visual consistency across the entire deck without splitting runs. Smaller windows force split-mode execution, which introduces visible style drift between phases. |
| 180 | - **AI image generation with `gpt-image-2`** (or similar): placeholder-grade stock images are the single biggest reason decks look generic. Replacing them with on-brand AI-generated illustrations changes the perceived quality immediately. |
| 181 | |
| 182 | If the results you've seen look mediocre, check your setup before concluding anything about the tool: What model? What context size? Was image generation enabled? PPT Master + Claude Opus at 1M context + `gpt-image-2` images is a genuinely different experience from PPT Master + a small open-source model with no image API configured. |
| 183 | |
| 184 | > **No Claude access?** Project sponsor [PackyCode](https://www.packyapi.ai/register?aff=ppt-master) provides pay-as-you-go access to Claude and other models — no subscription, no overseas card required. Use promo code **`ppt-master`** for 10% off. |
| 185 | |
| 186 | One last thing: this is a free, solo-maintained open-source project. If it fits your needs, use it — I'm glad it helps; if it doesn't, pick another tool. Sincere feedback and suggestions are always welcome, because that's how the project gets a little better over time. |
| 187 | |
| 188 | ## Q: Text overflows or elements are misaligned — what can I do? |
| 189 | |
| 190 | The cause depends on where the mismatch appears. If the source SVG already overflows or is misaligned, it is usually an authoring/layout problem: the model must calculate coordinates, font metrics, and container sizes correctly. If the SVG preview is correct but the exported PPTX differs, that may be a converter or renderer bug and should be reported with both artifacts. |
| 191 | |
| 192 | **Fixes to try**: |
| 193 | 1. Compare the page in `svg_output/` with the exported PPTX to isolate authoring from conversion |
| 194 | 2. Tell the AI which specific page has the problem and describe the issue — it can regenerate individual pages |
| 195 | 3. If the SVG itself is repeatedly wrong, use a stronger model or ask the AI to fix its coordinates directly |
| 196 | 4. Remember: the generated PPTX is a **high-quality editable draft**, not a sealed final deliverable — minor finishing adjustments in PowerPoint are expected |
| 197 | |
| 198 | ## Q: How long does a presentation take to generate? |
| 199 | |
| 200 | A typical 10–15 page presentation takes about **10–20 minutes** with a fast model. Generation is **intentionally serial** (one page at a time) to maintain visual consistency across slides — parallel generation was tested and produced inconsistent styles. |
| 201 | |
| 202 | If generation feels slow, check your model's token throughput. The bottleneck is usually the model's output speed, not the scripts. |
| 203 | |
| 204 | If what you want is less process rather than a different model, explicitly ask |
| 205 | for quick generation: it skips the Strategist analysis and the confirmation |
| 206 | stop, so the planning phase costs nothing, but per-page SVG authoring takes the |
| 207 | same time. See the next question, "I don't want to confirm a design spec first |
| 208 | — can I generate directly?". |
| 209 | |
| 210 | ## Q: I don't want to confirm a design spec first — can I generate directly? |
| 211 | |
| 212 | Yes. Explicitly request **quick generation**, and the Generate route uses the |
| 213 | [`quick-generate` profile](../skills/ppt-master/workflows/profiles/quick-generate.md). |
| 214 | |
| 215 | **What it skips is the Strategist analysis, the `design_spec.md` / |
| 216 | `spec_lock.md` artifacts, and the staged confirmation stop: whatever you state |
| 217 | explicitly is followed, and whatever you leave unspecified the current agent |
| 218 | decides directly and continues, without coming back for approval.** State |
| 219 | nothing, and the agent decides everything. It also skips `finalize_svg.py`, so |
| 220 | Quick creates no `svg_final/` preview. |
| 221 | |
| 222 | It does not skip preparation or design capability. Source conversion, research |
| 223 | on identified factual gaps, shared aesthetic references, and every resource the |
| 224 | deck needs still run when required: supplied or extracted images, |
| 225 | AI/web/sliced images, project icons, native shapes, charts/tables, rendered |
| 226 | formulas, and the required operational manifests or provenance records. If a |
| 227 | required asset is not ready, it still stops and asks you for it instead of |
| 228 | substituting unrelated material. After preparation, the current agent |
| 229 | hand-authors `svg_output/` to the shared standards, runs the lockless Quick |
| 230 | final quality checker, fixes every blocking error, and only then exports the |
| 231 | final PPTX. |
| 232 | |
| 233 | Ordinary exporter capabilities remain available as needed, including native |
| 234 | chart/table replacement, notes, motion, narration, and diagnostics. Notes, |
| 235 | custom object animation, and narration start off; the agent may enable them when |
| 236 | the request or deck needs them, without opening a confirmation flow. A |
| 237 | default-path export writes the normal postflight report and snapshots |
| 238 | `svg_output/` under `backup/`; an explicit output path keeps the ordinary |
| 239 | no-backup behavior. Page count alone neither activates nor blocks quick |
| 240 | generation. |
| 241 | |
| 242 | Because the whole planning phase no longer happens, token usage is materially |
| 243 | lower than the default flow; per-page SVG authoring is the dominant cost of a |
| 244 | run and it does not shrink. Quick keeps the same visual/resource authoring |
| 245 | capabilities and final blocking standard. It does not promise the same design |
| 246 | decisions or wall-clock time as Default because it has no confirmed design |
| 247 | contract, first-page calibration, or resumable decision history. |
| 248 | |
| 249 | ## Q: Will long decks blow out the context window in one shot? |
| 250 | |
| 251 | Default recommendation: **continuous one-shot generation**. 10–15 page decks fit comfortably in a 200K window, and cross-page visual consistency is best when the Executor can see prior pages in the same session (it actively aligns style, font sizes, and rhythm). |
| 252 | |
| 253 | When the current AI editor supports an isolated research worker, `topic-research` keeps raw fetches there and the main chat reads only the saved research supplement and fact-provenance file. |
| 254 | |
| 255 | Only when signals are heavy (≥ 18 pages, thick source material, or substantial research material remains in the main chat after a local fallback or unusually large imported supplement) does the AI surface an optional **split mode** hint at the Strategist phase: the planning session (Strategist confirmation stage + image acquisition) ends in the current chat; you open a fresh chat window and type `resume execution projects/<project_name>` to enter the execution session (SVG generation + export). The new session reloads `design_spec` / `spec_lock` / `sources` / `images` from disk and continues from there. |
| 256 | |
| 257 | Split mode is a **compromise** — the fresh session pays the fixed cost of reloading the Generate authority and required execution references, but drops the planning-session noise and reuses the freed budget to re-read `sources/` for richer slide content. **Not needed when signals are normal**; the hint won't appear, and you can always ignore it and stay in continuous mode. |
| 258 | |
| 259 | ## Q: Can I preview or fix individual pages before the full export? |
| 260 | |
| 261 | Yes. You can **interrupt the workflow at any time** — after the first few pages are generated, review them and give feedback. The AI can regenerate specific pages based on your comments. You don't need to wait until the end to make corrections. |
| 262 | |
| 263 | For post-generation fixes, simply tell the AI: "Page 3 has a layout issue — the title overlaps the chart" and it will fix that specific SVG. |
| 264 | |
| 265 | ## Q: I have an existing PPT and want to build on it — which route should I use? |
| 266 | |
| 267 | Think of "using an existing PPT" as two questions: **keep its content or not**, and **keep its design (layout + visuals) or not**. The four combinations map to three generation paths plus the option to keep the original unchanged: |
| 268 | |
| 269 | | Intent | Route | What stays fixed | |
| 270 | |---|---|---| |
| 271 | | Keep content + redo layout | **Generate PPTX + beautify profile** | Page count, page order, per-slide wording, chart/table data | |
| 272 | | Replace content + keep design | **Fill Native PPTX** | Native source slide design; selected pages may be reused/reordered | |
| 273 | | Keep only content, redo design and pagination | **Generate PPTX** | Source facts; story structure and page count may change | |
| 274 | | Keep content + keep design | No generation needed | Use the original file | |
| 275 | |
| 276 | Use the **beautify profile** when the source deck's page split is part of the requested output: text stays verbatim, page count and order are preserved 1:1, only layout / hierarchy / whitespace are redone while inheriting the original palette/fonts. Say "make this deck look better" / "re-layout this, keep the wording". See the [beautify profile](../skills/ppt-master/workflows/profiles/beautify-pptx.md). |
| 277 | |
| 278 | Use the **main pipeline** when the source PPT is just material: extract it to Markdown with `ppt_to_md`, read PPTX intake facts from `analysis/`, then let Strategist re-architect the outline freely (merge / split / reorder pages). Say "build a better deck from this one's content" or "turn this into a 10-page executive briefing". |
| 279 | |
| 280 | The one-line test between beautify and the main pipeline: **is the source's page split information to preserve, or just the previous author's structure to improve?** Preserve → beautify; improve → main pipeline. The concrete discriminator is **page count / order**: if it changes at all — split, merge, drop, reorder, or even keeping every word but splitting one crowded page so it reads better — that is re-pagination, which is the main pipeline. Beautify is strictly 1:1. |
| 281 | |
| 282 | If your request is ambiguous, for example "make this PPT more professional" or "optimize this deck", the AI should ask one clarification before routing: **keep the original page count/order and each slide's wording, or treat the PPT as source material and restructure it into a new story?** |
| 283 | |
| 284 | There is also one orthogonal route: if you don't want to produce a deck right now but want to **harvest the design into a reusable template** for future use, use **create-template** (see "How do I create a custom template?" below). |
| 285 | |
| 286 | --- |
| 287 | |
| 288 | ## Q: I already have a finished `.pptx` — can I reuse its design and just fill in new content? |
| 289 | |
| 290 | Yes — this is the **template fill** route, separate from the SVG generation pipeline. Give the AI your existing `.pptx` plus your material (or a topic) and ask it to "fill this deck with the new content" or "fill this back into the template". It treats your deck as a native slide library, lets you pick only the pages that fit the new story (reorder freely, and reuse one page for several output slides), and writes the new text — plus native table cells and chart data — straight into the original OOXML. |
| 291 | |
| 292 | The output stays 100% native-editable PowerPoint: the original design, layouts, images, and animations are preserved, and only the selected pages are exported. It deliberately does **not** change layouts, add pages, or swap images — a deck's page structure encodes its logic (lead-then-detail, comparison, progression), so pick pages whose structure already fits your content rather than forcing it in. For a fresh structure or a different page count, use create-template (next question) instead. Full steps: [template-fill workflow](../skills/ppt-master/workflows/template-fill-pptx.md). |
| 293 | |
| 294 | --- |
| 295 | |
| 296 | ## Q: How do I create a custom template? |
| 297 | |
| 298 | Want to turn a PPT you love into a reusable template for PPT Master? Here's how: |
| 299 | |
| 300 | **Step 1 — Prepare Reference Material** |
| 301 | |
| 302 | The recommended input is the original `.pptx`. PPT Master extracts theme identity, declared Master/Layout topology, placeholder metadata, native-shape evidence, and reusable assets that are actually present and supported. `standard` and `fidelity` use the source as visual reference and author a new SVG roster plus a new Master/Layout/slot system; they neither preserve nor distill source topology. `mirror` instead materializes those validated source facts into a new workspace without semantic synthesis or gap filling. Fixed Master/Layout group wrappers are mechanically expanded into direct atoms because structural layers cannot be `<g>`. |
| 303 | |
| 304 | Large imported SVGs may contain native-shape metadata, hidden carriers, and preview fingerprints. That lossless representation stays immutable in the temporary analysis workspace as payload backing. Template creation uses a lightweight editable IR with document-local source refs and a compact path/hash manifest. `standard` / `fidelity` author project-canonical SVG and use compact authored-preset groups only for exact registered preset matches. Mirror materializes final templates from the IR, reuses converter-supported payload only for unchanged Slide-local/slot refs, and keeps an SVG fallback for unsupported or edited objects. |
| 305 | |
| 306 | If no source PPTX exists, screenshots of the key page types still work — cover, TOC, chapter, content, and closing — but geometry, fonts, and inheritance must then be inferred visually. |
| 307 | |
| 308 | **Step 2 — Let AI Create the Template** |
| 309 | |
| 310 | Use an agent-capable AI tool (Claude Code, Codex, etc.) and ask it to use the **PPT Master `/create-template` workflow** to convert your reference material into a template. The more context you give, the better the result — for example: |
| 311 | |
| 312 | - Template name and intended use case (e.g., government reports, premium consulting) |
| 313 | - Desired tone and color palette (e.g., "modern and restrained, dark blue primary") |
| 314 | - Category preference (`brand` / `general` / `scenario` / `government` / `special`) |
| 315 | - Canvas format, if not the default 16:9 |
| 316 | - Output scope: indexed `library` (default) or one already initialized `project`; both use the same workspace routing and omit empty optional asset directories |
| 317 | |
| 318 | You don't need to supply every detail upfront — the AI agent will ask follow-up questions to fill in anything missing (output scope, template ID, theme mode, etc.). |
| 319 | |
| 320 | **Step 3 — Wait for the Result** |
| 321 | |
| 322 | The AI agent will handle the rest — analyzing your references, writing the kind-specific specification, building structured layout definitions only for Layout/Deck, and validating the workspace. Brand/Style never create a preview PPTX; Layout/Deck generate `exports/<id>_template_preview.pptx` on request and require it for multiple Masters. Both scopes require `templates/`; Brand/Layout/Deck may use package-owned `images/` and `icons/`, while Style contains only `templates/design_spec.md`. Library scope writes `skills/ppt-master/templates/<kind>/<id>/` and registers it; project scope writes `projects/<name>/` and skips registration. Empty optional directories are omitted. Give that workspace root to Step 3; it never copies `exports/`, and library review exports are Git-ignored. A compatible legacy-flat Brand/Layout/Deck workspace remains readable only when it satisfies the current kind contract; Layout/Deck also require current structured SVGs. Style has no legacy-flat form, and semantic-legacy packages must be replaced through `create-template` rather than upgraded in place. |
| 323 | |
| 324 | > **Tip**: The more specific you are about the style and use case, the better the generated template will match your expectations. |
| 325 | |
| 326 | --- |
| 327 | |
| 328 | > For more questions, see [SKILL.md](../skills/ppt-master/SKILL.md) and [AGENTS.md](../AGENTS.md) |
| 329 |