git clone https://github.com/rocsgh/ppt-zen cd ppt-zen ./install.sh auto # detects your runtimes; matrix below for one-by-one
| Runtime | Command | Installs to | Trigger |
|---|---|---|---|
| Claude Code | ./install.sh claude [--global] | .claude/skills/ppt-zen/ | /ppt-zen or just ask for a deck |
| OpenClaw | ./install.sh openclaw [--global] | .openclaw/skills/ppt-zen/ | ask for a deck |
| Hermes | ./install.sh hermes | ~/.hermes/skills/creative/ppt-zen/ | ask for a deck |
| Codex CLI | ./install.sh codex [--global] | AGENTS.md / ~/.codex/AGENTS.md | passive — auto-read |
| Cursor | ./install.sh cursor | .cursor/rules/ppt-zen.mdc | passive — auto-applied |
| Windsurf | ./install.sh windsurf | .windsurf/rules/ppt-zen.md | passive — auto-applied |
| GitHub Copilot | ./install.sh copilot | .github/instructions/ | passive — auto-applied |
| everything | ./install.sh all | all of the above | — |
| auto | ./install.sh auto | every runtime detected on this machine | — |
Project-level rows install into the current directory — Codex, Cursor, Windsurf and Copilot all write beside whatever project you are standing in, so run the installer from your project, not from inside the clone: cd my-project && /path/to/ppt-zen/install.sh codex. It rewrites the skill's file references to absolute paths so they still resolve from over there.
Skill installs are self-contained (SKILL.md + references + styles + scripts + examples + styles.json + requirements.txt). No skill system at all? Paste SKILL.md into the session as context.
Hermes: there is no project-level skill directory — the installer always writes to $HERMES_HOME/skills (default ~/.hermes/skills), so --global is a no-op. Restart your Hermes gateway/process afterwards: the skill index is cached in-process. Hermes’ builtin powerpoint skill (text-box decks) keeps working alongside it; for designed full-image decks ppt-zen supersedes it.
Every page is a generated image, and PPT-Zen ships none. Which half applies to you:
| Your runtime | What you do |
|---|---|
| Claude Code · Codex · Cursor · Windsurf · Copilot | You need an image key — the 30-second .env setup below. |
| Hermes (or any agent with its own image tool) | Nothing to configure. The skill uses the tool the agent already has. |
Already export OPENAI_API_KEY? | Nothing to configure either — the helper reuses it silently. |
Bring your own key: any endpoint that implements the OpenAI /images/generations API (accepts {model, prompt, size, n}, returns b64_json or url — chat-only "compatible" gateways don't count):
cp .env.example .env # IMAGE_API_BASE_URL / IMAGE_API_KEY / IMAGE_MODEL / IMAGE_SIZE python3 scripts/gen_image.py --check # doctor: reads your config, generates one test image
--check is the support story: it masks your key, probes the endpoint, and turns whatever went wrong into one plain verdict with the fix — bad key, chat-only gateway, unreachable host. Ready-to-paste .env blocks for OpenAI, generic relays and 火山方舟 / 豆包 Seedream: references/providers.md.
PPT-Zen ships no key and no model — the judgment is open source, the pixels are yours. A hosted trial that skips this step is coming.
No key today? Ask for the deck anyway. You get the judgment pack: the per-page plan with a ready-to-paste prompt for every page, placeholder pages, and an assembled draft.pptx. Paste any prompt into an image tool you already have, drop the result into slides/, reassemble. The key becomes an optional last step.
Open your agent in any project and talk. One sentence starts it; the skill decides the rest and never quizzes you about layout:
"Make me a 10-page pitch deck about <your project> with ppt-zen, in the Portolan style." "Design a keynote about our Q3 results — pick a material that fits." # it chooses "One slide only: '23 minutes to refocus', make it land." # single page
The agent writes slides/PLAN.md (page · density · device · exact text · style) — review it if you like — then generates one image per page into slides/. Iterate by pointing at pages:
"Regenerate page 6 — the numbers feel cramped."
"Swap the whole deck to the Kintsugi material." # same plan, new world
"Page 4's device isn't readable, try a funnel."
Feed it your facts. Attach an outline / metrics / links — real numbers land on the slides; anything missing shows as [TO CONFIRM] rather than an invented figure. When the pages read clean:
pip install python-pptx python3 scripts/assemble_pptx.py slides/ deck.pptx
Anything behind an OpenAI-compatible /images/generations route — OpenAI's gpt-image models, relays, gateways. The gallery samples were generated with gpt-image class models at 1536×1024. Non-16:9 output is center cover-cropped at assembly, so prompts keep key content clear of the top/bottom ~8%.
It's image-based: each slide is one full-bleed image. Present it, export PDF, or import into Keynote/Google Slides — but text isn't editable. Fixing a typo means regenerating that one page (the skill supports single-page regeneration).
No — that's a hard rule. Facts come from your input; anything missing becomes a visible [TO CONFIRM] placeholder. The skill decides form, never facts.
Yes — copy styles/_template/, fill in the STYLE.md (material recipe + a sample), open a PR. The gallery and styles.json regenerate automatically. Styles are CC-BY-4.0, contributions via DCO.
Whatever your image endpoint charges — a 10-page deck is 10 images plus any single-page retries. Order of magnitude (OpenAI gpt-image list prices, mid-2026): roughly $0.06–0.25 per 1536×1024 image depending on quality tier, so a first pass is about $1–3; budget 20–40 minutes including proofreading. Check your own endpoint's pricing.