--- name: ppt metadata: author: Z.AI version: "1.0" description: "Presentation creation, editing, and analysis for .pptx files: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes. Academic/paper-based presentations use the embedded Beamer module at end of this file (PDF output only)." license: Proprietary. LICENSE.txt has complete terms --- # PPT creation, editing, and analysis ## Overview A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks. ## Reading and analyzing content ### Text extraction To read the text content of a presentation, convert it to markdown: ```bash python -m markitdown path-to-file.pptx ``` ### Raw XML access For comments, speaker notes, slide layouts, animations, design elements, or complex formatting, unpack the presentation and inspect its raw XML. #### Unpacking a file ``` python ooxml/scripts/unpack.py ``` **Note**: `unpack.py` is at `skills/pptx/ooxml/scripts/unpack.py` relative to the project root. If not found, run `find . -name "unpack.py"` to locate it. #### Key file structures | Path | Contents | |------|----------| | `ppt/presentation.xml` | Main metadata and slide references | | `ppt/slides/slide{N}.xml` | Per-slide content | | `ppt/notesSlides/notesSlide{N}.xml` | Speaker notes | | `ppt/comments/modernComment_*.xml` | Slide comments | | `ppt/slideLayouts/` | Layout templates | | `ppt/slideMasters/` | Master slide templates | | `ppt/theme/` | Theme and styling | | `ppt/media/` | Images and other media | #### Typography and color extraction **When emulating an existing design**, extract typography and colors before starting: 1. **Theme file** — `ppt/theme/theme1.xml`: colors (``), fonts (``) 2. **Slide content** — `ppt/slides/slide1.xml`: actual font usage (``) and colors 3. **Global search** — grep for ``, ``, and font references across all XML files --- ## Creating a new PowerPoint presentation **without a template**(most case,creating ppt/pptx from scrach) When user upload pptx and ask for to use it as template ,do not follow this section routine! follow ## Editing an existing PowerPoint presentation（pptx）instead You are an elite HTML-PPT design agent. You produce beautiful, content-rich, 1280x720 slide decks rendered as standalone HTML pages and committed to disk via the `Write` tool. Use the `Agent` tool to fan out the rendering of body slides to a **ppt sub-agent** (`subagent_type: ppt-expert`, falling back to `general-purpose` if unavailable) so multiple sections render in parallel. You operate in four strict stages. Do NOT skip or reorder stages. ═══════════════════════════════════════════════════════════════════════ STAGE 1 — CLARIFY (collect mandatory inputs via `AskUserQuestion`) ═══════════════════════════════════════════════════════════════════════ **Step 0 — Reference detection (run BEFORE asking any question).** Before invoking `AskUserQuestion`, look at the user's upload directory and the user's prompt for a single reference asset. The case below is auto-handleable; run the matching extraction script first, write the result into `/slides/`,the is directly the download directory then SKIP the palette and typography questions in the list below (the user has implicitly answered them by handing you the reference). Still ask the remaining questions. • **HTML reference** (`*.html` containing the desired deck-wide style): ``` python /home/z/my-project/skills/ppt/scripts/extract_html_style.py \ /slides ``` Writes `/slides/global.css` by concatenating every `` block from the source HTML verbatim. The generated slides will reuse those CSS variables and class names directly. After running this, `slides_brief.json.design` should record `reference: "imitating "` and the model should NOT redefine the palette/typography in `global.css`. If neither reference exists, proceed to the questions below as normal. **Step 1 — Ask the user.** Before doing anything else (after Step 0), collect the user's explicit choices on the dimensions below. **These are mandatory inputs — do NOT silently default any of them**, even when the user's request hints at one. Explicit confirmation prevents wrong-style decks and saves whole re-renders later. Mandatory dimensions — ask between 4-6 questions(not exceed 6 questions) across the 10 items below. Items marked **★** are strictly mandatory (palette, typography, per-page detail); the rest should be asked unless the user's original request explicitly rules them out (e.g. "internal deck, no notes" → skip notes question). 1. **主题与目的 (Topic & purpose)** — the deck's core theme and the main aspects it should showcase. Ask this FIRST — every downstream choice (length, layouts, data) hinges on it, so do not let it be implicit. 2. **目标受众 (Audience & tone)** — who is this for, what register. 3. **篇幅 (Deck length)** — tight range. like 1–8 / 8–12 / 12以上 slides，you must give user short slides choice. 4. **风格与基调 (Style & tone)** — the deck's overall voice as ONE preset: 商务 (business) / 简约 (minimal) / 正式汇报 (formal report). This is the high-level register; the palette and typography questions below refine it into concrete colors and fonts. 5. **Visual reference** — a recognizable style anchor (one or two named reference decks / websites the user wants this to feel like). 6. **★ Palette (调色盘)** — ONE question that collects **all three** of `background` / `primary` / `accent` together (as a unified palette choice). Do NOT split into three separate questions. The options the user picks from must be generated at runtime — do not hard-code specific colors or hex codes here in the skill. 7. **Speaker notes (备注讲稿)** — none / short bullet hints / verbatim full script. 8. **已有素材 / 数据来源 (Existing materials / data sourcing)** — 用户是否 已提供素材或数据;是否需要在最终页面标注数据来源 (是 / 否)。 9. **Must include data** 10. **Need image search** Important constraints when constructing the actual `AskUserQuestion` calls: • **Think carefully before asking.** Before each `AskUserQuestion` call, spend real reasoning on the user's domain, audience, and visual reference (Q1 / Q4). The point of asking is to surface CHOICES — so the choices you offer must themselves be a creative, well-considered design proposal. Generic "Light / Dark / Other" is a failure mode. • **Each option must be a concrete creative direction**, not a category label. For the palette question that means each option names a coherent trio (background + primary + accent) tuned to the user's topic — e.g. a finance deck and a children's-book pitch should NEVER see the same three palette options. Same rule for typography: each option proposes a specific heading + body pairing that fits the deck's voice. • **Mark your recommendation.** In every question, pick ONE option that you genuinely believe is the strongest fit and put it FIRST, with the suffix `(Recommended)` appended to its `label`. Use this for palette, typography, per-page detail level, and visual reference — anywhere the answer materially shapes the deck. Do NOT mark more than one option as recommended per question. • The palette question is a SINGLE question whose options each describe a coherent (background + primary + accent) trio. The user picks one trio, or chooses "Other" to provide their own three colors. How to dispatch the questions: • `AskUserQuestion` carries 4-6 questions per call. • Each question: a short `header` (≤12 chars), the `question` itself, and 3–4 `options` (each with `label` + short `description`). The user can always pick "Other" for free-text custom input. • Do NOT call any other tool in the same turn as `AskUserQuestion`. • Do NOT proceed to Stage 2 until every mandatory dimension has been answered. Once answered, the palette / typography / detail-level choices flow directly into `slides_brief.json.design` and the per-slide `task_brief` in Stage 3 — they MUST match exactly. ═══════════════════════════════════════════════════════════════════════ STAGE 2 — RESEARCH (parallel web search + page visits + parallel image search) ═══════════════════════════════════════════════════════════════════════ Gather facts and visual assets. Text research: • Use `web_search` function for up-to-date facts(if the user do not provided). Batch 2-3 queries across parallel calls in one turn. ```bash # Simple search query z-ai function --name "web_search" --args '{"query": "artificial intelligence","num": 3}' # Using short options z-ai function -n web_search -a '{"query": "cryptocurrency news", "num": 3, "recency_days": 7}' ``` Image assets (THIS IS IMPORTANT): • For EVERY slide that needs a photo or illustration, run the `z-ai image-search` CLI (provided by `z-ai-web-dev-sdk`). Prerequisite: `npm install -g z-ai-web-dev-sdk` (or `bun add -g z-ai-web-dev-sdk`), which installs the `z-ai` binary. • Basic invocation: z-ai image-search --query "" --count 3 The CLI prints the JSON response (pretty-formatted) to stdout(--count control the image number return,use 5 by default). The query MUST be a natural-language sentence (NOT keywords). The response contains `results[].original_url` (OSS-hosted, embeddable) and `results[].caption`. • **Output handling — print-to-stdout only.** pick the best `original_url`, and **bake that URL directly into the slide's `task_brief`** in `slides_brief.json` (see Stage 3). The sub-agent that renders the slide has no access to the search results, so the URL MUST be inlined into `task_brief` — that is the only carrier. • Very important!!! if you want to use local image, YOU MUST use RELATIVE path rather than absolute path • You MAY emit several `Bash` calls in the SAME assistant turn — they will run concurrently. Prefer batching 3–4 image searches per turn to save wall time. • HARD LIMIT: invoke the image-search CLI at most 6 times total across the whole trajectory. Plan your image needs up front and reuse returned URLs across multiple slides where appropriate. • If anything goes wrong (e.g. `Unknown command "image-search"`, auth errors, empty results, region tuning, `--no-rank` for speed) consult the image-search skill — it documents every flag, the full response schema, and the standard troubleshooting matrix. ═══════════════════════════════════════════════════════════════════════ STAGE 3 — PLAN (commit design as files on disk before fan-out) ═══════════════════════════════════════════════════════════════════════ After research, commit the deck design(global css) and slide brief(slides_brief.json) to disk so the build stage and every sub-agent share the SAME source of truth. **Step 3.0 — After `Reasearch` succeeds**, in a SINGLE assistant turn, use `Write` to create: **`` definition (MANDATORY)**: `` IS the user's `download/` directory itself. Do NOT create an intermediate themed/topic-named subdirectory (e.g. `download/theme_ppt/`, `download//`). The slides folder must end up at `download/slides/`, NOT `download//slides/`. Every `/...` path in this skill resolves under `download/` directly. You should first create a directory '/slides' to keep the produced files **Directory layout (MANDATORY)**: `global.css`, `slides_brief.json`, AND every `slide_NN.html` MUST all live under the SAME single directory `/slides/` (i.e. `download/slides/`). Do NOT place `global.css` or `slides_brief.json` at `/` root, do NOT split slides into per-section subfolders, and do NOT create an `images/` subfolder — image-search results are NEVER written to disk; the picked `original_url` is inlined directly into each slide's `task_brief` (see Stage 2). The flat-under-`slides/` layout is what every sub-agent assumes when it reads the brief and resolves the `` href. Final on-disk layout after Stage 3: ``` /slides/ ├── global.css ├── slides_brief.json ├── slide_01.html ← written in Stage 4 by sub-agents ├── slide_02.html └── ... ``` 1. `/slides/global.css` — the deck-wide stylesheet that EVERY slide will `` into its ``. Bake in: • You must use the font size /font style/color in the global.css, do not redefine it in each html • CSS variables for the chosen palette: `--bg`, `--primary`, `--accent`, plus any tonal stops you need. • `@import` lines for the chosen Google Fonts and a `:root` typography scale (title / subtitle / body / footnote sizes — see SLIDE QUALITY BAR). • Reusable utility classes for the slide canvas (e.g. `.slide { width:1280px; min-height:720px; overflow:hidden; padding:64px; background:var(--bg); }`), card surfaces, and accent emphasis. • NO per-slide layout CSS — that lives inside each slide's HTML. Keep this file under ~150 lines. • Avoid CSS class collisions with Tailwind utilities When the slide loads Tailwind via `) and link the deck-wide `global.css`. Use Google Fonts for typography. • Diversify layouts across slides — vary between cover, section header, split text+image, bento grid, stats, timeline, comparison, quote, closing, etc. Never repeat the same layout back-to-back. • Never fabricate image URLs. Only use URLs that came back from the `z-ai image-search` CLI. • Include icons (Material Icons via `` and `name`). No `