codex-ppt git:20260618.680ddaeA

Immutable. This exact content never changes and is served at /api/v1/blob/901772bd923a610e.

---
name: codex-ppt
description: Generate visually unified image-based PPT/PPTX decks from articles, reports, papers, notes, or outlines.
metadata:
  openclaw:
    requires:
      bins:
        - python3
    primaryEnv: OPENAI_API_KEY
    envVars:
      - name: OPENAI_API_KEY
        required: false
        description: API key for CLI fallback.
      - name: OPENAI_BASE_URL
        required: false
        description: API base URL.
      - name: CODEX_PPT_IMAGE_MODEL
        required: false
        description: Image model, defaults to gpt-image-2.
      - name: CODEX_PPT_HOME
        required: false
        description: Runtime home override.
    homepage: https://github.com/ningzimu/codex-ppt-skill
---

# Codex PPT

## Overview

This skill creates image-based PowerPoint decks from source material. Each slide is a complete 16:9 generated image. 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.

Prefer `scripts/image_gen.py --backend auto` for slide image generation. In Codex this normally selects Codex OAuth and writes directly to the project-local image path.

## Hard Constraints

- Read the relevant `Reference Map` files before each phase. This file is the orchestration contract; detailed rules live in `docs/` and worker prompts in `prompts/`.
- 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 the user approves the sample slide and the workflow reaches full-deck generation, every remaining slide image job must be dispatched to a slide subagent whenever subagents are available. Do not ask for separate user authorization to use subagents.
- Keep subagent dispatch slots full: whenever a slide subagent finishes and its result is recorded, immediately check pending jobs and dispatch the next slide into the freed slot.
- The main agent owns orchestration, prompt jobs, state recording, QA, speaker notes, and assembly. Do not silently replace available slide subagents with sequential production.
- Every final `origin_image/slide_XX.png` must be generated by the selected image backend, normally `scripts/image_gen.py --backend auto`.
- 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 the sample slide is generated. Do not let subagents switch backend for convenience.
- After the PPT is assembled, if the user asks to change specific details on one slide, use the selected backend's edit capability on that existing slide image instead of regenerating from a text-only prompt, to avoid style and detail drift.
- After sample approval, record the approved sample's backend, tool, model/config, and generation-mode rule. Subagents should use `generate` for new slides by default, and use `edit` only for strict input assets or repairs.
- Slide dispatch and result state must be recorded with the bundled scripts. Chat messages alone do not make a slide dispatched or complete.
- 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, and style decisions.
2. Generate and approve one sample slide.
3. Prepare slide jobs and slide state.
4. Dispatch slide subagents.
5. Record generated slide results.
6. QA, repair, notes, and PPT assembly.

Do not mark a step complete from chat alone; use real files or script-recorded state.

## Default Workflow

1. Understand the source content.
   - Identify topic, audience, goal, page count, style/brand constraints, and sections to include or exclude.
   - If no page count is specified, choose a practical count. Typical decks are 8-12 slides.

2. Plan the deck outline.
   - Before writing or updating `outline.md`, read `docs/workflow-gates-and-progress.md` and `docs/outline-style-and-sample.md`.
   - Draft slide roles and required source images. Ask for confirmation, then stop before style, sample, or downstream artifacts until approved.

3. Confirm a unified visual style.
   - Before offering style options or using files from `references/`, read `docs/outline-style-and-sample.md`.
   - Offer 2-3 concrete style directions, recommend one, wait for confirmation, then keep one visual identity while varying layouts by page role.

4. Select and announce the image backend.
   - Before generating any slide image, read `docs/backend-selection.md`.
   - Select the backend from the rules, state which backend will be used when generating the sample, then continue to sample generation. Do not ask for separate backend confirmation.
   - Read `docs/cli-api-fallback.md` before using `scripts/image_gen.py`. Read `docs/image-model-configuration.md` only after config errors or explicit API-setting requests.

5. Generate one sample slide for approval.
   - Before generating or approving the sample slide, read `docs/outline-style-and-sample.md`.
   - Generate exactly one representative sample after outline and style are confirmed, and state which backend was used. Do not generate the full deck until the sample is approved.
   - After approval, record `sample_generation_method` in `deck_spec.json` so jobs and subagents inherit the same backend/config and mode rule.

6. Create the project directory.
   - Before initializing folders or assembling files, read `docs/project-assembly-and-reporting.md`.
   - If no destination is specified, use the current working directory or the source file directory.

7. Prepare user-supplied assets.
   - Before using paper figures, charts, screenshots, logos, or other required assets, read `docs/user-supplied-assets.md`.
   - Treat required assets as strict inputs and confirm slide-to-asset mapping before generation.

8. Generate all slide images.
   - Before full-deck image generation, read `docs/slide-generation-and-subagents.md`.
   - Create per-slide jobs with `scripts/prepare_slide_prompts.py` or saved `prompts/slide_XX.json` files.
   - Every final image must come from the selected backend and be recorded with bundled state scripts.

9. Dispatch slide subagents.
   - Before dispatching or replacing slide workers, read `docs/slide-generation-and-subagents.md` and `prompts/slide-worker.md`.
   - Use one subagent per remaining slide job whenever possible. If subagent tools are available in the current runtime, dispatch them directly; do not add an extra user-authorization gate.
   - After any worker returns, record the result, rerun `slide_job_status.py`, and immediately dispatch the next pending slide into the freed slot.

10. 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.

11. 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, ensure `slide_jobs.json` shows generated slides as `recorded` and approved samples as `accepted`. If any slide is `pending`, `dispatched`, or `blocked`, stop.

12. Report the result.
    - Use the final report checklist in `docs/project-assembly-and-reporting.md`.
    - Include paths, slide count, backend used, recorded-result status, and any limitations or blockers.

13. Save reusable styles when requested.
    - If asked to save the current deck style or a supplied image/PDF/PPT/PPTX style, read `docs/style-library.md`.

## Subagent Dispatch

Slide subagents are mandatory after sample approval whenever the runtime can spawn them. Availability means the subagent tool is visible and callable in the current runtime; the main agent must not ask for separate user authorization before dispatching. The main agent prepares jobs and records state; each worker handles exactly one `prompts/slide_XX.json` job and returns only selected image path, backend, and QA note.

Treat subagent dispatch as a refill loop, not a one-time batch: after each returned worker is recorded, use the updated slide state to fill the newly available slot with the next pending slide.

Use `docs/slide-generation-and-subagents.md` for dispatch, commands, result recording, blockers, and backend provenance. Use `prompts/slide-worker.md` as the handoff template.

Subagents must not edit `outline.md`, `deck_spec.json`, other slide jobs, `origin_image/`, `speech.md`, or the final `.pptx`. The parent records outputs and assembles.

## Acceptance Criteria

- Output is a valid `.pptx`.
- Each expected final slide image exists under `origin_image/slide_XX.png`.
- Every final slide image was generated by the selected backend and recorded through `record_slide_result.py`, except an approved sample marked accepted by run state.
- `outline.md` reflects the approved deck outline.
- `speech.md` exists when speaker notes are expected, and assembly writes those notes into the PPT.
- `slide_jobs.json` and `slide_run_state.json` reflect the final state.
- 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`: backend decision rules and sample-generation announcement text.
- `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-and-subagents.md`: jobs, dispatch, result recording, blockers, provenance.
- `docs/cli-api-fallback.md`: fallback runtime, generation/edit commands, image limits, troubleshooting.
- `docs/image-model-configuration.md`: API key, base URL, model, `.env`; read only when config is needed.
- `docs/project-assembly-and-reporting.md`: project directory, notes, assembly, final report, prompting principles.
- `prompts/slide-worker.md`: slide subagent handoff template.
- `references/*.md`: visual style references.

## Documentation and Updates

For source, docs, install, config, and examples, see [ningzimu/codex-ppt-skill](https://github.com/ningzimu/codex-ppt-skill).