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, a third-party image API, or an OpenAI-compatible image generation endpoint. 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.

Sponsor

Thanks to Atlas Cloud for sponsoring this project. AtlasCloud is a multimodal AI inference platform that provides one API for image generation, video generation, LLMs, and more. This skill can use the existing API key, base URL, and model-name configuration to call AtlasCloud's GPT Image 2 generation and editing endpoints, with pay-as-you-go pricing and out-of-the-box setup. See the full model list on the Atlas Cloud models page.

Friendly Note

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页。"

For more practical notes on designing and tuning this PPT skill, see the Chinese article 2000 个 GitHub Star 换来的经验：好的 AI Skill 是调出来的，不是写出来的.

Note

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

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 save it into your personal style library at ~/.codex-ppt-skill/references/ and gradually build your own collection. The personal style library lives outside the skill install directory, so updating or reinstalling the skill never loses it. 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

• Works across multiple agents: supports Codex, Claude Code, OpenClaw, Hermes Agent, and other SKILL.md-based environments; Codex is the recommended environment because it can use the built-in image generation and image editing tools first.
• Supports third-party image providers: works with OpenAI-compatible endpoints, AtlasCloud, base URL, and custom model names, so API/CLI fallback can use gpt-image-2 or compatible image models.
• Stable staged workflow: confirms the outline, slide count, visual style, image backend, and sample slide before full-deck generation, reducing drift and rework when generating a complete PPT.
• Guided instead of one-shot: the skill asks you to confirm outline.md, per-slide key points, style direction, and sample-slide quality before continuing.
• Low setup effort: articles, reports, papers, course notes, Markdown files, outlines, PDFs, and Word documents can all be used as starting material.
• 12 built-in PPT style references: includes clean professional, scientific defense, Party-and-Government Red, Teaching Courseware, e-ink magazine, hand-drawn technical explainer, dashboard, McKinsey style, and more. The hand-drawn technical explainer style is a strong starting point if you do not want to write prompts.
• Supports custom style replication: provide a favorite image, PDF, or PPT/PPTX, and the agent can analyze its color, layout, typography, and visual system before generating a new deck in that style.
• Builds a reusable personal style library: once you like a deck style, ask the agent to save it into ~/.codex-ppt-skill/references/ so future decks can reuse it directly; the library lives outside the skill install, survives skill updates, and a personal style with the same name takes priority over the built-in one.
• Supports parallel subagent generation: after the sample slide is approved, one subagent can handle one slide and self-check readability, style consistency, and content completeness before reporting issues for repair.
• Supports required image insertion: assign paper figures, experiment charts, screenshots, architecture diagrams, or other images to specific slides, and the generated page will adapt the layout and theme around them.
• Generates speaker notes: creates speech.md and writes the notes into each slide during PPTX assembly, making the deck easier to present or revise.

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
Party-and-Government Red	Teaching Courseware

Output Structure

Each PPT is generated into an independent project directory:

{base_dir}/{deck_name}/     # Independent project directory for this deck
├── origin_image/           # Final slide images only
│   ├── slide_01.png        # Slide 1 image
│   ├── slide_02.png        # Slide 2 image
│   └── ...                 # Additional slide images, named in slide order
├── outline.md              # Confirmed outline, slide count, titles, and key points
├── speech.md               # Speaker notes written into the PPT
└── {deck_name}.pptx        # Final assembled PowerPoint file

Use origin_image/ to review the final image used for each slide. Files are named in order as slide_01.png, slide_02.png, and so on, which makes it easy to preview the deck visually or ask for one specific slide to be revised.

speech.md is the companion talk track. When the .pptx is assembled, the content is written into each slide's speaker notes so you can view, edit, or use it directly while presenting in PowerPoint.

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

One-sentence install

Recommended: send this sentence to your agent and let it install the skill for you:

Please install this codex-ppt skill for me: https://github.com/ningzimu/codex-ppt-skill

Manual install for Codex

To install manually for Codex, use the skills CLI to add this skill to 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. You can also 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

Tip

You can start using Codex PPT normally to make a deck. In most cases, you do not need to configure the image model by hand; when the workflow asks you to choose an image backend, the AI will check the current environment and guide you through any required information.

• If you use Codex's built-in image generation, you usually do not need an extra API key.
• If you have confirmed that a third-party provider or OpenAI-compatible proxy is needed, ask the AI to read the image model configuration guide before configuring API key, base URL, and model name.

Asking for a specific resolution, higher quality, or edits to one slide does not by itself trigger third-party API configuration. If you use Codex through a GPT subscription and Codex's built-in image generation tool is available, you can usually keep using the built-in image tool and do not need to prepare an API key.

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.
11. Optional: if you really like the generated PPT style, save it to the style library; if it already uses a built-in style, you do not need to save it again.

Usage Tips

• Codex subscribers use the built-in image generation tool by default; its output resolution is relatively low, and it does not currently expose a manual resolution setting. If you need higher-resolution images, switch to generating via the gpt-image-2 API (the API/CLI fallback path, configured with an API key, base URL, and model name). In the API/CLI fallback path, the default script resolution is 2K 16:9 landscape; if slide images still look blurry, especially on text-heavy pages, ask the AI to switch to 4K.
• 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 your personal style library at ~/.codex-ppt-skill/references/ for future reuse; it will not be lost when the skill is updated.
• 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

• Documentation: 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.

Telegram: CodexPPT

More Projects

• image-to-editable-ppt-skill: Rebuild slide screenshots, PDF pages, or image-based PPTX files into editable PowerPoint decks, useful after codex-ppt generates image-based slides.
• codex-gpt-image: A gpt-image-2 image generation skill powered by Codex OAuth / member login.
• handdrawn-tech-illustrations: A hand-drawn illustration skill for Chinese technical content. It turns technical articles, product notes, screenshots, outlines, or rough ideas into article illustrations, concept explainer graphics, WeChat cover images, and Rednote covers, with a friendly, light-cartoon, Chinese-readable style and moderate information density.
• awesome-ai-ppt: A curated list of open-source AI PPT projects, organized by workflows such as HTML-first, image-first, PPTX-native, conversion, and automation infrastructure, focused on GitHub projects that help agents or developers create, edit, convert, or inspect PPT decks.
• claude-code-lens: A local observability tool for Claude Code API traffic, logs, prompts, and tool calls, useful for understanding what an agent is actually doing.

License

MIT

Acknowledgements

Thanks to the LinuxDO community for its support.

Star History