Codex PPT Skill

What It Does

codex-ppt generates image-based PowerPoint decks from source material like articles, reports, papers, and course notes. Each slide is a complete 16:9 generated image (produced by gpt-image-2 or an OpenAI-compatible endpoint), and the final images are assembled into a .pptx file by a local script. The skill follows a staged workflow: it plans an outline, confirms a visual style, generates one sample slide for approval, then dispatches remaining slides to subagents in parallel. It targets developers and content creators who want visually unified presentations and accept that slide elements are not individually editable after generation. The skill works across Codex (recommended), Claude Code, OpenClaw, and Hermes Agent.

The Good

The orchestration contract is exceptionally well-engineered. The SKILL.md defines a 13-step workflow with explicit approval gates: outline confirmation, style confirmation, backend confirmation, and sample-slide approval must all pass before full-deck generation begins. A 158-line SKILL.md acts as the orchestration entrypoint, while 10 phase-specific doc files (totaling 2,099 lines of markdown) carry the detailed rules. This progressive disclosure pattern keeps the entrypoint lean while making every phase auditable. The hard constraints section is unusually specific, listing exactly what the main agent owns (orchestration, prompt jobs, state recording, QA, speaker notes, assembly) versus what subagents own (one slide each, returning only image path, backend, and QA note).

The state machine is real and it works. Six Python scripts manage slide job lifecycle with file-locking: prepare_slide_prompts.py creates per-slide JSON job specs and a slide_jobs.json state file, record_slide_dispatch.py logs subagent dispatch, record_slide_blocker.py records failures, record_slide_result.py copies generated images, and slide_job_status.py reports state in both human-readable and JSON formats. The filelock dependency (from PyPI) prevents concurrent corruption when multiple subagents update state. In testing, the full pipeline ran cleanly: prepare created 2 slide jobs, dispatch moved slide 1 to "dispatched", blocker moved slide 2 to "blocked", and status reported correct counts with dispatch slots available. This is not a wrapper around an API. It is a genuine multi-agent coordination layer.

PPTX assembly is correct and handles real edge cases. The assemble_ppt.py script (438 lines) sorts slides by numeric page number (avoiding the slide_10-before-slide_2 trap), compresses images over 2MB using Pillow with progressive quality reduction and dimension scaling, parses speaker notes from speech.md using regex that handles both English (## Slide N) and Chinese (## 第 N 页) heading formats, and supports 16:9 and 4:3 aspect ratios. In testing, it assembled 3 dummy 1920x1080 PNGs into a 42KB Microsoft OOXML PPTX with correct 10x5.625 inch dimensions (ratio 1.778) and all 3 speaker notes correctly written to their respective slides.

Cross-agent compatibility is taken seriously, not just claimed. The skill ships install instructions for four agent platforms (Codex, Claude Code, OpenClaw, Hermes Agent) with matching skills CLI commands. The runtime is explicitly designed to be shared across agents: a single venv at ~/.codex-ppt-skill/.venv and a single .env at ~/.codex-ppt-skill/.env serve all of them. The codex_ppt_runtime.py script provides bootstrap, config, and doctor subcommands for managing this shared runtime. The doctor command checks Python imports, API key presence (masked), base URL, and model name validation.

12 built-in style references with real visual briefs. Each style file (ranging from 72 to 138 lines) is a structured JSON brief with canvas specs, color palettes (hex values), composition rules, typography guidance, and use-case lists. Styles include Clean Professional, Scientific Defense, McKinsey Style, Data Dashboard, Hand-drawn Technical Explainer, Teaching Courseware, Party-and-Government Red, and Creative Magazine. The README ships 12 corresponding preview images generated with gpt-image-2. A personal style library at ~/.codex-ppt-skill/references/ lets users save custom styles that survive skill updates and take priority over built-in styles with the same name.

The Bad

No test suite for the Python scripts. The repo has four CI workflows (release, publish-clawhub-skill, pr-title, changelog-check) but none run pytest or any functional tests on the 3,717 lines of Python. The CI validates changelog format, PR titles, and release packaging, but not script behavior. For a skill with file-locking, state management, and image processing logic, this is a gap. The scripts work in practice (this review verified them), but there is no regression protection.

The documentation is Chinese-primary, which limits international reach. The orchestration docs (backend-selection.md, cli-api-fallback.md, the slide-worker prompt) are in English, which is good. But all 12 style reference files, all Python docstrings and inline comments, the confirmation text templates in docs, and the primary README are in Chinese. The English README (README_en.md) is a complete translation, but the in-skill reference material that an agent actually reads during generation is Chinese. Non-Chinese-speaking users will get decks that work but may not understand the style briefs their agent is consuming. This is an ecosystem-fit limitation, not a quality flaw.

The venv dependency creates a setup friction point. Every script that imports python-pptx, Pillow, or openai will fail with "dependencies not installed" if run with the system Python instead of the runtime venv Python. The scripts include a helpful dependency_hint() function pointing to the bootstrap command, but an agent that does not read the docs first will hit this error. In testing, running assemble_ppt.py with system Python produced "error: python-pptx not installed" despite the venv being bootstrapped. The fix is to always use ~/.codex-ppt-skill/.venv/bin/python, but this is not documented prominently enough in the SKILL.md itself (it lives in the docs).

image_gen.py is 965 lines with limited error transparency for non-Codex users. The fallback CLI handles generate, generate-batch, and edit subcommands with OpenAI-compatible providers, AtlasCloud detection, and model name validation. But for Claude Code, OpenClaw, and Hermes Agent users, the primary path is the built-in image tool, and the CLI fallback requires explicit API key configuration that the skill prompts for only after a failure. A user who wants to use this skill outside Codex needs to understand the backend selection rules before starting, or they will encounter confusing mid-workflow prompts.

Smoke Test Results

Host-based testing on macOS (aarch64). The repo was cloned to /tmp/codex-ppt-skill (86MB with assets). All scripts tested with the runtime venv Python after bootstrap.

Run A - Fresh sandbox, no deps preinstalled

$ python3 codex_ppt_runtime.py bootstrap
Creating virtual environment: /tmp/codex-ppt-test-home/.venv
Installing dependencies from: .../requirements.txt
Successfully installed Pillow-12.3.0 python-pptx-1.0.2 openai-2.45.0 filelock-3.29.7
Runtime ready: /tmp/codex-ppt-test-home
exit: 0 ✓

$ python3 codex_ppt_runtime.py doctor
runtime home: /tmp/codex-ppt-test-home
venv python: /tmp/codex-ppt-test-home/.venv/bin/python
dependencies: ok
OPENAI_API_KEY=<unset>
CODEX_PPT_IMAGE_MODEL=gpt-image-2
model check: ok
exit: 0 ✓

$ python3 codex_ppt_runtime.py config --api-key "***" --model "gpt-image-2"
Wrote /tmp/codex-ppt-test-home/.env
OPENAI_API_KEY=*** (sk-t...5678)
CODEX_PPT_IMAGE_MODEL=gpt-image-2
exit: 0 ✓

$ python3 assemble_ppt.py --help ✓
$ python3 image_gen.py --help ✓
$ python3 prepare_slide_prompts.py --help ✓
$ python3 record_slide_dispatch.py --help ✓
$ python3 record_slide_blocker.py --help ✓
$ python3 record_slide_result.py --help ✓
$ python3 slide_job_status.py --help ✓
$ python3 remove_chroma_key.py --help ✓

Pass rate: 8 of 8 scripts. All scripts install, bootstrap, and expose help correctly.

Full sandbox log ->

Run B - Sandbox with deps preinstalled

$ venv_python assemble_ppt.py /tmp/work TestDeck --init
✓ PPT project dir ready
✓ Slide image dir ready
exit: 0 ✓

$ venv_python assemble_ppt.py /tmp/work TestDeck
Found 3 slide images
Found 3 speaker notes in speech.md
Creating PPT (aspect ratio: 16:9)...
✓ Added slide 1: slide_01.png
✓ Added slide 2: slide_02.png
✓ Added slide 3: slide_03.png
✓ PPT file saved: TestDeck.pptx (3 pages, notes: 3/3)
exit: 0 ✓

PPTX verification:
 file: Microsoft OOXML
 slide count: 3
 dimensions: 10.000 x 5.625 inches (16:9 = 1.778)
 slide 1: 1 shape, notes='Intro text here.'
 slide 2: 1 shape, notes='Main content.'
 slide 3: 1 shape, notes='Closing.'

Pass rate: 3 of 3. The assembly pipeline produces a valid PPTX with correct dimensions, shapes, and speaker notes parsed from markdown.

Full sandbox log ->

Run C - Functional verification (state machine pipeline)

$ venv_python prepare_slide_prompts.py --spec deck_spec.json --out-dir mydeck --selected-backend builtin
Wrote 2 slide job file(s) to mydeck/prompts
Wrote slide job state to mydeck/slide_jobs.json
exit: 0 ✓

$ venv_python record_slide_dispatch.py mydeck --slide 1 --agent-id worker-001 --agent-nickname slide-bot
slide_01 -> dispatched
exit: 0 ✓

$ venv_python slide_job_status.py mydeck
run_status=jobs_prepared
active_dispatches=slide_01
dispatch_slots_available=5
dispatchable_slides=slide_02
exit: 0 ✓

$ venv_python record_slide_blocker.py mydeck --slide 2 --reason "Image backend unavailable"
slide_02 -> blocked
exit: 0 ✓

$ venv_python slide_job_status.py --json mydeck
{
 "run_status": "blocked",
 "slide_count": 2,
 "dispatch_slots_available": 5,
 "counts": { "dispatched": 1, "blocked": 1 }
}
exit: 0 ✓

Functional pass rate: 5 of 5. The full state machine works: job preparation, subagent dispatch, status reporting, blocker recording, and JSON status output all behave correctly.

Full functional log ->

What the runs tell you

The assembly and state-management scripts are production-grade and work exactly as documented. The only untested component is image_gen.py, which requires a real gpt-image-2 API key for actual image generation. Everything else, from venv bootstrapping through PPTX assembly with speaker notes, is fully verified. The skill's core claim (turn source text into visually unified image-based decks) is supported by the working infrastructure, even though the final image generation step needs a paid API.

Setup Walkthrough

1. Install the skill for your agent. For Codex: npx -y skills@latest add ningzimu/codex-ppt-skill --skill codex-ppt --agent codex --global. For Hermes Agent, replace --agent codex with --agent hermes-agent.
2. Bootstrap the runtime venv. The first time the skill runs, or manually via python3 ~/.codex/skills/codex-ppt/scripts/codex_ppt_runtime.py bootstrap. This creates a venv at ~/.codex-ppt-skill/.venv with python-pptx, Pillow, openai, and filelock.
3. In Codex, you can usually start generating immediately using the built-in image tool. In Claude Code, OpenClaw, or Hermes Agent, you may need to configure an image API key: python3 codex_ppt_runtime.py config --api-key sk-... --model gpt-image-2.
4. Invoke the skill: "Use the codex-ppt skill to turn /path/to/article.md into a roughly 10-slide PPT."
5. The skill will guide you through outline confirmation, style selection, backend confirmation, and a sample slide before generating the full deck. Each gate requires your approval.

Post-install gotcha: if scripts fail with "python-pptx not installed", you are running the system Python instead of the venv Python. The runtime venv lives at ~/.codex-ppt-skill/.venv/bin/python.

Alternatives

1. ningzimu/image-to-editable-ppt-skill - the companion skill that converts image-based PPTX (like codex-ppt output) back into editable PowerPoint with real text boxes. Use codex-ppt for visual impact, then this for editability.
2. ConardLi/garden-skills (web-design-engineer) - a different approach to visual generation that focuses on web design and React components rather than PPT slides. Broader visual scope but not PPT-specific.
3. python-pptx (the library) - for developers who want full programmatic control over PPTX generation without the AI-guided workflow. More work, but every element stays editable.