ningzimu__codex-ppt-skill/README_en.md

Codex PPT Skill

A Codex skill for generating PowerPoint decks. It can also be used in Claude Code, OpenClaw, Hermes Agent, and other agents that support SKILL.md; these non-Codex environments usually require configuring gpt-image-2 or a third-party OpenAI-compatible image generation API. It turns articles, reports, papers, course notes, and other source materials into image-based presentations: first plan the outline and visual style, then generate each full-slide image, and finally assemble the images into a .pptx file with a local script.

Tip

This skill generates image-based PPT decks from articles, reports, outlines, or ideas. It is suitable for strong visual expression, but slide elements are not directly editable. If you need a more editable PPT, you can try converting the generated deck with image-to-editable-ppt-skill.

For a detailed introduction to codex-ppt and image-to-editable-ppt, see skill_duo_intro.pdf. This deck was generated with the codex-ppt skill using the prompt: "请分别阅读 Codex PPT和 Image to Editable PPT 这两个技能的内容，然后用 Codex PPT 帮我做一个PPT吧，20页，每个技能的介绍10页。"

Note

To see more PPT examples made by users with this skill, visit the pinned showcase issue: 欢迎分享 codex-ppt 使用案例和 PPT 效果.

Friendly Note

This skill is meant to provide a solid PPT generation workflow. To stay broadly useful, the workflow is a little more complex than most people need every day, and that complexity can sometimes add instability or redundant choices. For example, it supports both Codex built-in image generation and API/CLI fallback generation, and it also supports workflows with or without subagents. Most users will eventually use only one of those paths.

After you have a route working, consider asking an AI assistant to edit this skill and lock in your own preferences, such as your preferred image backend, whether to use subagents, output directory conventions, visual styles, or slide pacing. That way you do not need to make the same choices every time.

If you find a layout or visual style you like while making decks, whether it was generated by this skill or found elsewhere, you can ask AI to add it to this skill's references/ directory and gradually build your own style library. Skills are highly personal workflows; tune this one around your own habits so it becomes more useful for your actual work.

For a basic introduction to skill design and usage, see good-skill-design.pptx. That deck was also made with this skill, using the hand-drawn technical explainer style, and is based on Claude's skill design best-practices article The Complete Guide to Building Skills for Claude.

Features

• Uses Codex's built-in image generation and editing capabilities when available; uses the local CLI/API fallback in other agents.
• Supports multiple agent environments, including Codex, Claude Code, OpenClaw, and Hermes Agent.
• Supports gpt-image-2 image models provided by third-party OpenAI-compatible endpoints.
• Image-based PPT workflow: each slide is a complete 16:9 image, suitable for highly visual presentations.
• Supports assigning required image assets to specific slides, such as paper figures, experiment charts, screenshots, or architecture diagrams.
• Style reference library: includes clean professional, scientific defense, e-ink magazine, hand-drawn technical explainer, dashboard, and other style directions.
• Keeps one coherent visual language across the whole deck, while varying layouts by slide semantics to avoid mechanical repetition.
• Local assembly script: packages slide_01.png, slide_02.png, and other generated images into a PowerPoint file.

Output Example

Below is an example technical sharing deck. Each page is a complete 16:9 slide image generated by gpt-image-2, then assembled into a PPTX file by the local script.

Below is a scientific defense example based on the paper Attention Is All You Need. It shows how to assign original paper figures to specific slides as input assets, such as the model architecture, attention modules, and attention visualizations, then generate a coherent deck around those figures (see Issue #14).

Style Examples

The following preview images were generated with gpt-image-2 to help users choose a visual direction before production.

Clean Professional	Creative Magazine
E-ink Magazine	Data Dashboard
Retro Flat Illustration	Hand-drawn Technical Explainer
Hand-drawn Whiteboard	Warm Handmade
Scientific Defense	McKinsey Style

Output Structure

Each PPT is generated into an independent project directory:

{base_dir}/{deck_name}/
├── origin_image/
│   ├── slide_01.png
│   ├── slide_02.png
│   └── ...
├── outline.md
├── speech.md
└── {deck_name}.pptx

origin_image/ should contain only final slide images, named in order as slide_01.png, slide_02.png, and so on. The confirmed sample slide should also use its final slide filename directly. If you want to keep rejected variants or comparison drafts, put them in the project root or a separate drafts/ directory, not in origin_image/.

speech.md is written into PowerPoint speaker notes during assembly. Use headings such as ## Slide 1: Title and ## Slide 2: Title; the script matches notes by slide number.

Use Cases

• Turn technical articles into sharing decks.
• Turn papers or reports into presentations.
• Turn course notes into teaching slides.
• Create decks for research proposals, midterm reviews, final project acceptance, and thesis defenses.
• Create business reports, product introductions, and research summaries.
• Produce image-based presentations that require strong visual consistency.

Installation

Codex

Use the skills CLI to install this skill into Codex's global skills directory:

npx -y skills@latest add ningzimu/codex-ppt-skill \
  --skill codex-ppt \
  --agent codex \
  --global

Restart Codex after installation so the new skill is picked up.

You can also download codex-ppt-skill-v*.zip from GitHub Releases, unzip it, place the contained codex-ppt directory at ~/.codex/skills/codex-ppt, and then restart Codex.

If you are developing this repository locally, you can instead symlink the skill directory into the Codex skills directory so changes are reflected immediately:

mkdir -p ~/.codex/skills
ln -s /path/to/codex-ppt-skill/skills/codex-ppt ~/.codex/skills/codex-ppt

OpenClaw

Install from ClawHub:

openclaw skills install codex-ppt

ClawHub page: clawhub.ai/ningzimu/codex-ppt

If you use OpenClaw skill allowlists, add codex-ppt to the allowed skills.

Claude Code and Hermes Agent

These agents can read SKILL.md skills. The recommended path is to install with the skills CLI:

# Claude Code
npx -y skills@latest add ningzimu/codex-ppt-skill \
  --skill codex-ppt \
  --agent claude-code \
  --global

# Hermes Agent
npx -y skills@latest add ningzimu/codex-ppt-skill \
  --skill codex-ppt \
  --agent hermes-agent \
  --global

Common target directories are ~/.claude/skills/codex-ppt for Claude Code and ~/.hermes/skills/codex-ppt for Hermes Agent.

If you are developing this repository locally, you can use a symlink instead of copying so changes are reflected immediately.

Image Model Configuration

You only need to configure an image model when API/CLI fallback image generation is needed. Asking for a specific resolution, higher quality, or edits to one slide does not by itself trigger third-party API configuration; if Codex's built-in image tool is available, it should keep using the built-in tool. Typical cases that require configuration include:

• Using a third-party API or OpenAI-compatible proxy in Codex, where the built-in image generation tool is usually unavailable.
• Using this skill from Claude Code, OpenClaw, Hermes Agent, or similar agents.

If you use Codex through a GPT subscription and Codex's built-in image generation tool is available, you do not need to configure the gpt-image-2 image model; in that setup, Codex already provides the image generation capability. Even when the user explicitly says “use gpt-image-2”, treat that as a request to use Codex's built-in image tool first, not as a reason to switch to the local API/CLI fallback.

Only after API/CLI fallback has been intentionally selected should the agent check ~/.codex-ppt-skill/.env and report a missing OPENAI_API_KEY. Do not ask for an API key in Codex just because the user mentioned gpt-image-2 while the built-in image tool is available. base URL is only needed when using a third-party proxy, and the model defaults to gpt-image-2; change the model only when your proxy requires a custom model name. After that, Codex, Claude Code, OpenClaw, and Hermes Agent reuse the same config.

For manual troubleshooting, you can also run the config command directly:

python3 /path/to/codex-ppt-skill/skills/codex-ppt/scripts/codex_ppt_runtime.py config \
  --api-key "your-api-key" \
  --model gpt-image-2

--api-key is your API key. --model is the image model name, and gpt-image-2 is the default choice. The config is written to ~/.codex-ppt-skill/.env. Do not write API keys into the project directory or commit them to the repository.

If you use a third-party proxy, add --base-url. If the proxy uses a custom model name, replace --model with the name provided by that proxy:

python3 /path/to/codex-ppt-skill/skills/codex-ppt/scripts/codex_ppt_runtime.py config \
  --api-key "your-api-key" \
  --base-url "https://your-openai-compatible-endpoint/v1" \
  --model openai/gpt-image-2

Usage

Ask Codex, Claude Code, OpenClaw, or Hermes Agent and explicitly specify the codex-ppt skill, for example:

Use the codex-ppt skill to turn /path/to/article.md into a roughly 10-slide PPT.

The skill follows this workflow:

1. Read the source content and plan the deck outline.
2. Generate outline.md and ask you to confirm slide count, slide titles, and key points.
3. Offer 2-3 visual style options and recommend one for user confirmation.
4. State the image generation backend before the first image and ask you to confirm it.
5. Generate one sample slide with the confirmed image backend for approval of style, layout rhythm, and text quality.
6. Create the PPT project directory.
7. Generate all slide images one by one with the same image backend.
8. Check text readability, style consistency, and content completeness.
9. Generate speech.md.
10. Assemble the .pptx with assemble_ppt.py.

Usage Tips

• The default script resolution is 2K 16:9 landscape. If generated slide images look blurry, especially on text-heavy pages, ask the current agent to generate the images at 4K resolution.
• If you are unhappy with one specific slide's content, layout, colors, or wording, ask the current agent to refine that slide in detail instead of regenerating the whole deck.
• You can also provide PPT style references you like — a single screenshot, multiple screenshots, or a full PPT/PDF. Ask the current agent to analyze the colors, layout, typography, and visual elements first, then generate a new deck in that style. Once the result looks good, you can ask the agent to save the style into this skill's references/ directory for future reuse.
• If you need to include paper figures, experiment charts, screenshots, or architecture diagrams, specify the target slide and role for each image in the outline.

QA

• Feishu doc: codex-ppt FAQ and usage notes

Community

Scan the QR code to join the Skill community group, share usage experience, report issues, and receive update notices.

License

MIT

Star History