ai-image-ppt git:20261021.8838379A

Immutable. This exact content never changes and is served at /api/v1/blob/5bb2158633a99a80.

---
name: ai-image-ppt
description: Generate visually unified image-based PPT/PPTX decks from articles, reports, papers, notes, or outlines.
---

# AI Image PPT

## Overview

This skill creates image-based PowerPoint decks from source material. Each slide is a complete generated image, defaulting to 16:9. Supported ratios are `16:9` (default), `4:3`, `1:1`, `3:4`, `9:16`, and `21:9`. If another supported ratio is requested, use it consistently in prompts, image dimensions, and PPT assembly. Final images are assembled into `.pptx` with `scripts/assemble_ppt.py`.

Use this when the user wants a visually unified presentation and accepts full-slide image pages. Do not use it when every textbox, chart, or shape must remain separately editable.

If a built-in image generation tool is available, select it directly as the image backend without reading `docs/backend-selection.md`, `docs/cli-api-fallback.md`, or `docs/image-model-configuration.md`. Otherwise, read those three files and then select the image backend. Backend selection does not require user confirmation.

## Hard Constraints

- Read the relevant `Reference Map` files before each phase. This file is the orchestration contract; detailed rules live in `docs/` and per-slide guidance in `prompts/`.
- Require outline, visual-style (unless already clearly specified), and sample confirmation by default. Skip sample confirmation also when inspection verifies consistency with a user-provided style reference image. Otherwise waive confirmation only on explicit user request, following `docs/workflow-gates-and-progress.md`; never infer a waiver from silence or a general creation request.
- Respect approval gates. Do not create final `deck_spec.json`, `speech.md`, prompt jobs, slide images, or `.pptx` before the approvals in `docs/workflow-gates-and-progress.md`.
- After sample approval, generate remaining slides in batches of at most 6 concurrent image calls in the main agent using the selected backend. Do not delegate slide generation to subagents.
- The main agent owns prompt jobs, generation, image saving, QA, notes, and assembly.
- Every final `origin_image/slide_XX.png` must be generated by the selected image backend: built-in image generation/editing tool or `scripts/image_gen.py`.
- Local drawing, Pillow, SVG, HTML/CSS/canvas screenshots, python-pptx/PptxGenJS layouts, and manual overlays are failure modes, not fallbacks.
- The selected image backend must stay fixed after backend selection. Do not switch backend for convenience.
- After sample approval, record the sample generation method and retain its backend and visual settings; allow generation/edit mode to vary with image-input and repair needs.
- A slide is generated successfully if and only if its expected `origin_image/slide_XX.png` file exists. Do not create separate task-state files.
- If the selected image backend or a required-image path is unavailable, stop and report a blocker with the slide id and evidence. Do not create a lower-quality replacement.

## Visible Progress

For non-trivial decks, keep a user-visible checklist with one active step. Canonical completion evidence is in `docs/workflow-gates-and-progress.md`.

Default visible steps:

1. Prepare source, outline, style, and backend decisions.
2. Generate and approve one sample slide.
3. Prepare slide prompts.
4. Generate images in batches in the main agent (up to 6 concurrent calls).
5. Save generated slide images.
6. QA, repair, notes, and PPT assembly.

Do not mark a step complete from chat alone; use actual output files.

## Default Workflow

1. Prepare source material, project directory, and assets.
   - Read `docs/project-assembly-and-reporting.md` before initializing folders and `docs/user-supplied-assets.md` before using source images.
   - Identify topic, audience, goal, language, page count, and required or excluded content. Default to a practical 8-12 slides.
   - Choose the output directory and initialize the project folders before writing the outline or generating a sample. Use the current working directory or source directory when no destination is given.
   - Extract and inspect required assets, recording their paths and roles. Folder initialization does not authorize downstream production.

2. Plan and confirm the outline.
   - Read `docs/workflow-gates-and-progress.md` and `docs/outline-style-and-sample.md`.
   - Write `outline.md` with titles, key points, page roles, and required image mappings. Obtain approval before style selection or generation, unless the user explicitly waived confirmation.

3. Confirm the visual style.
   - Read `docs/outline-style-and-sample.md`.
   - If the user supplied a clear style or visual reference, extract and briefly restate its rules. Otherwise offer 2-3 built-in style directions and recommend one for confirmation.
   - Keep one visual identity while varying page layouts by content.

4. Select the image backend.
   - If a built-in image generation tool is available, select it directly. Do not read `docs/backend-selection.md`, `docs/cli-api-fallback.md`, or `docs/image-model-configuration.md` on this path.
   - Otherwise, read those three files, then select the image backend.

5. Generate and approve one sample.
   - Read `docs/outline-style-and-sample.md` and generate one representative slide after the outline and style are approved and the backend is selected.
   - Save it under its final `origin_image/slide_XX.png` name. Obtain approval before full production unless the user explicitly waived sample confirmation or inspection verifies that the sample matches a user-provided style reference image; apply the checks in `docs/outline-style-and-sample.md`.

6. Prepare the deck specification and jobs.
   - Read `docs/slide-generation.md`.
   - Create `deck_spec.json`, including the approved sample method and `approved_style_reference`. Keep the approved sample image at its final path.
   - Run `prepare_slide_prompts.py` to create per-slide prompt files. Reuse the approved sample: its final image already exists.

7. Generate and save each remaining slide.
   - Read `prompts/slide-generation.md` and execute jobs whose expected final images are missing in batches of at most 6 concurrent image calls in the main agent. Do not delegate.
   - For each job, call the selected backend, inspect the candidate, repair as needed, and save or copy the chosen generated image to its expected `origin_image/slide_XX.png` path. Finish and save all results in the current batch before launching the next batch.
   - Keep the backend and visual identity fixed. Choose generation or editing according to required image inputs and repair needs; sample mode is provenance, not a mandatory mode for every call.
   - On failure, report the page and reason; leave its final image absent. After the cause is resolved, retry the missing page without any state reset.

8. Quality check and repair.
    - Before QA or assembly, read `docs/project-assembly-and-reporting.md`.
    - Inspect every slide before assembly: text, outline match, truncation, style, unwanted page numbers, overlaps, and required assets.
    - Regenerate severe failures with a tighter prompt. Use backend editing for localized issues when available.
    - For CLI/API fallback edit commands, read `docs/cli-api-fallback.md`. Replace the final slide only after validating the edited output.

9. Write speaker notes and assemble the PPT.
    - Before writing `speech.md` or running assembly, read `docs/project-assembly-and-reporting.md`.
    - Make sure `outline.md` reflects the final confirmed deck outline. Use `speech.md` headings that map to `Slide N`.
    - Before assembly, check every expected image path from `deck_spec.json`. Stop if any image is missing; do not rely on file count alone.

10. Report the result.
    - Use the final report checklist in `docs/project-assembly-and-reporting.md`.
    - Include paths, slide count, generated/missing slide counts, and any limitations or blockers.


## Main-Agent Generation

Execute saved slide jobs directly in the main agent in batches of at most 6 concurrent image calls, using the selected backend and approved visual settings. Each call handles one slide. Wait for every call in a batch to finish, inspect and save each result, then start the next batch only if all expected images in that batch exist. Repairs and retries count toward the same limit. Use smaller batches or serial calls if the runtime/backend cannot parallelize. Do not create subagents.

## Acceptance Criteria

- Output is a valid `.pptx`.
- Each expected final slide image exists under `origin_image/slide_XX.png`.
- Every final slide image comes from the selected image backend, including the reused approved sample.
- `outline.md` reflects the approved deck outline.
- `speech.md` exists when speaker notes are expected, and assembly writes those notes into the PPT.
- Required source images are visibly represented, or a blocker is reported.
- If blocked, the final response identifies phase, slide id, evidence path, and unfinished reason; do not call the deck complete.

## Reference Map

- `docs/workflow-gates-and-progress.md`: approval gates, progress, completion evidence.
- `docs/backend-selection.md`: read when no built-in image generation tool is available.
- `docs/outline-style-and-sample.md`: outline, style, sample rules, prompt examples.
- `docs/user-supplied-assets.md`: strict handling for required source assets.
- `docs/slide-generation.md`: prompts, batched generation, image saving, and retries.
- `docs/cli-api-fallback.md`: read when no built-in image generation tool is available; runtime, commands, limits, troubleshooting.
- `docs/image-model-configuration.md`: read when no built-in image generation tool is available; API key, base URL, model, `.env`.
- `docs/project-assembly-and-reporting.md`: project directory, notes, assembly, final report, prompting principles.
- `prompts/slide-generation.md`: main-agent per-slide checklist.
- `references/*.md`: built-in visual style references.