# ningzimu/codex-ppt-skill architecture

> Architecture diagram of the GitHub repository ningzimu/codex-ppt-skill, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ningzimu/codex-ppt-skill
- Repository: https://github.com/ningzimu/codex-ppt-skill

## Overview

Codex PPT is an agent skill that turns source material into image-based PowerPoint decks. Its documented workflow guides the user through outline, page count, style, backend, and sample approval; slide prompts/jobs are then prepared for generation, selected images are recorded, and a local assembler creates the PPTX with speaker notes. The README also documents reusable built-in/personal styles, custom reference assets, required images, concurrent slide agents, and API/CLI image fallbacks. Some workflow capabilities are documented but their implementation was not sampled, so those connections are shown at the skill boundary rather than inferred script-to-script.

Main entry points: [`skills/codex-ppt/SKILL.md`](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/SKILL.md) (PPT workflow), [`skills/codex-ppt/scripts/record_slide_result.py`](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/record_slide_result.py) (Record slide result), [`skills/codex-ppt/scripts/image_providers/factory.py`](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/image_providers/factory.py) (Provider selection), [`skills/codex-ppt/scripts/assemble_ppt.py`](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/assemble_ppt.py) (PPTX assembler)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Planning and style"]
  node_skill["PPT workflow<br/>[SKILL.md]"]
  node_style_library["Style references"]
  node_custom_assets["Custom references"]
  node_outline["Outline and speech<br/>[SKILL.md]"]
end

subgraph group_generation["Slide generation"]
  node_prompt_prep["Prompt preparation"]
  node_slide_jobs[("Slide jobs and state<br/>[slide_run_state.py]")]
  node_slide_workers["Slide workers<br/>[slide-worker.md]"]
  node_image_cli["Image CLI<br/>[image_gen.py]"]
  node_slide_result["Record slide result"]
  node_run_state[("Run state helpers<br/>[slide_run_state.py]")]
  node_chroma["Chroma processing"]
end

subgraph group_assembly["Deck assembly"]
  node_slide_images["Final slide images"]
  node_assembler["PPTX assembler<br/>[assemble_ppt.py]"]
end

subgraph group_runtime["Runtime and providers"]
  node_provider_factory["Provider selection<br/>[factory.py]"]
  node_openai_provider["OpenAI-compatible"]
  node_atlas_provider["AtlasCloud<br/>[atlascloud.py]"]
  node_shared_runtime["Shared agent runtime"]
end

node_user(("User"))
node_agent(("Host agent"))
node_source_material["Source material"]
node_image_service{{"Image API"}}
node_pptx["PowerPoint deck"]

node_user -->|"requests deck"| node_agent
node_source_material -->|"provides content"| node_agent
node_agent -->|"invokes workflow"| node_skill
node_skill -->|"confirms outline"| node_outline
node_skill -->|"offers styles"| node_style_library
node_skill -->|"analyzes references"| node_custom_assets
node_skill -->|"prepares slides"| node_prompt_prep
node_prompt_prep -->|"writes jobs"| node_slide_jobs
node_skill -->|"dispatches slides"| node_slide_workers
node_slide_workers -.->|"requests images"| node_image_cli
node_image_cli -->|"selects provider"| node_provider_factory
node_provider_factory -->|"creates provider"| node_openai_provider
node_provider_factory -->|"creates provider"| node_atlas_provider
node_openai_provider -->|"sends generation request"| node_image_service
node_atlas_provider -->|"submits prediction"| node_image_service
node_skill -->|"records selected output"| node_slide_result
node_slide_result -->|"updates job state"| node_run_state
node_slide_result -->|"copies selected image"| node_slide_images
node_skill -.->|"removes key color"| node_chroma
node_slide_images -->|"reads slide images"| node_assembler
node_outline -->|"supplies speaker notes"| node_assembler
node_assembler -->|"writes deck"| node_pptx
node_shared_runtime -.->|"configures environment"| node_openai_provider

click node_skill "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/SKILL.md"
click node_style_library "https://github.com/ningzimu/codex-ppt-skill/tree/main/skills/codex-ppt/references"
click node_custom_assets "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/docs/user-supplied-assets.md"
click node_outline "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/SKILL.md"
click node_prompt_prep "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/prepare_slide_prompts.py"
click node_slide_jobs "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/slide_run_state.py"
click node_slide_workers "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/prompts/slide-worker.md"
click node_image_cli "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/image_gen.py"
click node_provider_factory "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/image_providers/factory.py"
click node_openai_provider "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/image_providers/openai_compatible.py"
click node_atlas_provider "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/image_providers/atlascloud.py"
click node_slide_result "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/record_slide_result.py"
click node_run_state "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/slide_run_state.py"
click node_chroma "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/remove_chroma_key.py"
click node_assembler "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/assemble_ppt.py"
click node_shared_runtime "https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/codex_ppt_runtime.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_skill,node_style_library,node_custom_assets,node_outline,node_user toneBlue
class node_prompt_prep,node_slide_jobs,node_slide_workers,node_image_cli,node_slide_result,node_run_state,node_chroma toneAmber
class node_slide_images,node_assembler,node_image_service toneMint
class node_provider_factory,node_openai_provider,node_atlas_provider,node_shared_runtime toneRose
class node_agent,node_source_material,node_pptx toneIndigo
```

## Components

### Planning and style

- [PPT workflow](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/SKILL.md): `skills/codex-ppt/SKILL.md`
- [Style references](https://github.com/ningzimu/codex-ppt-skill/tree/main/skills/codex-ppt/references): `skills/codex-ppt/references`
- [Custom references](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/docs/user-supplied-assets.md): `skills/codex-ppt/docs/user-supplied-assets.md`
- [Outline and speech](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/SKILL.md): `skills/codex-ppt/SKILL.md`

### Slide generation

- [Prompt preparation](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/prepare_slide_prompts.py): `skills/codex-ppt/scripts/prepare_slide_prompts.py`
- [Slide jobs and state](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/slide_run_state.py): `skills/codex-ppt/scripts/slide_run_state.py`
- [Slide workers](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/prompts/slide-worker.md): `skills/codex-ppt/prompts/slide-worker.md`
- [Image CLI](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/image_gen.py): `skills/codex-ppt/scripts/image_gen.py`
- [Record slide result](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/record_slide_result.py): `skills/codex-ppt/scripts/record_slide_result.py`
- [Run state helpers](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/slide_run_state.py): `skills/codex-ppt/scripts/slide_run_state.py`
- [Chroma processing](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/remove_chroma_key.py): `skills/codex-ppt/scripts/remove_chroma_key.py`

### Deck assembly

- **Final slide images**
- [PPTX assembler](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/assemble_ppt.py): `skills/codex-ppt/scripts/assemble_ppt.py`

### Runtime and providers

- [Provider selection](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/image_providers/factory.py): `skills/codex-ppt/scripts/image_providers/factory.py`
- [OpenAI-compatible](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/image_providers/openai_compatible.py): `skills/codex-ppt/scripts/image_providers/openai_compatible.py`
- [AtlasCloud](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/image_providers/atlascloud.py): `skills/codex-ppt/scripts/image_providers/atlascloud.py`
- [Shared agent runtime](https://github.com/ningzimu/codex-ppt-skill/blob/main/skills/codex-ppt/scripts/codex_ppt_runtime.py): `skills/codex-ppt/scripts/codex_ppt_runtime.py`

### Other components

- **User**
- **Host agent**
- **Source material**
- **Image API**
- **PowerPoint deck**

## Connections

- User → Host agent: requests deck
- Source material → Host agent: provides content
- Host agent → PPT workflow: invokes workflow
- PPT workflow → Outline and speech: confirms outline
- PPT workflow → Style references: offers styles
- PPT workflow → Custom references: analyzes references
- PPT workflow → Prompt preparation: prepares slides
- Prompt preparation → Slide jobs and state: writes jobs
- PPT workflow → Slide workers: dispatches slides
- Slide workers → Image CLI: requests images
- Image CLI → Provider selection: selects provider
- Provider selection → OpenAI-compatible: creates provider
- Provider selection → AtlasCloud: creates provider
- OpenAI-compatible → Image API: sends generation request
- AtlasCloud → Image API: submits prediction
- PPT workflow → Record slide result: records selected output
- Record slide result → Run state helpers: updates job state
- Record slide result → Final slide images: copies selected image
- PPT workflow → Chroma processing: removes key color
- Final slide images → PPTX assembler: reads slide images
- Outline and speech → PPTX assembler: supplies speaker notes
- PPTX assembler → PowerPoint deck: writes deck
- Shared agent runtime → OpenAI-compatible: configures environment