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 the built-in image generation/editing tool. Use scripts/image_gen.py only when the built-in backend is unavailable, lacks a required capability, or the user explicitly asks for API/CLI mode.
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 authorizes full-deck generation, every remaining slide image job must be dispatched to a slide subagent whenever subagents are available.
- 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: 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 confirmation. Do not let subagents switch backend for convenience.
- After sample approval, record how the approved sample was generated and pass that exact method to every slide subagent.
- Slide dispatch and result state must be recorded with the bundled scripts. Chat messages alone do not make a slide dispatched or complete.
- If a required subagent, image backend, or 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:
- Prepare source, outline, style, and backend decisions.
- Generate and approve one sample slide.
- Prepare slide jobs and slide state.
- Dispatch slide subagents.
- Record generated slide results.
- QA, repair, notes, and PPT assembly.
Do not mark a step complete from chat alone; use real files or script-recorded state.
Default Workflow
-
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.
-
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, backend, sample, or downstream artifacts until approved.
-
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.
-
Confirm the image backend.
- Before generating any slide image, read
docs/backend-selection.md.
- Check whether a built-in image tool is callable, state what you checked, name the backend, explain fallback status, and wait for confirmation.
- If CLI/API fallback is selected, read
docs/cli-api-fallback.md. Read docs/image-model-configuration.md only after config errors or explicit API-setting requests.
-
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, style, and backend are confirmed. Do not generate the full deck until approved.
- After approval, record
sample_generation_method in deck_spec.json so jobs and subagents inherit the same path.
-
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.
-
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.
-
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.
-
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 required subagents cannot be spawned, stop and report a blocker unless the user changes the workflow.
-
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.
-
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.
-
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.
-
Save reusable styles.
- If asked to save the current deck style or a supplied image/PDF/PPT/PPTX style, read
docs/style-library.md.
- If the final deck used a custom or adapted style, proactively offer to save it in the final report, per
docs/project-assembly-and-reporting.md. User custom styles are stored in ${CODEX_PPT_HOME:-~/.codex-ppt-skill}/references/, outside the skill install.
Subagent Dispatch
Slide subagents are mandatory after sample approval whenever the runtime can spawn them. 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.
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 confirmed 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 confirmation 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: built-in visual style references. User custom styles live in ${CODEX_PPT_HOME:-~/.codex-ppt-skill}/references/ and take priority over built-in styles with the same name.
Documentation and Updates
For source, docs, install, config, and examples, see ningzimu/codex-ppt-skill.