image2-PPT Skill

Turn per-page Markdown design specs into a visually consistent PowerPoint deck — each page is rendered by a text-to-image API, then assembled into a .pptx with python-pptx.

📖 中文说明

---

What it does

This skill is the rendering half of a two-step slide-generation workflow:

[Page design step]  →  one .md design spec per slide (P01_cover_v1.md, P02_agenda_v1.md, …)
        │
        ▼
[This skill]  image2-PPT
        │  ① read each .md in page order
        │  ② extract the embedded `image2` prompt, append a global style-lock block
        │     and cross-page narrative context
        │  ③ call your text-to-image API (≤3 concurrent, resume on interruption)
        │  ④ assemble the returned slide images into a 16:9 .pptx
        ▼
[final_presentation.pptx]   +  one-click single-page regenerate & replace

Key capabilities:

• Phase-driven pipeline — Phase 1 renders anchor pages (P01–P04) serially for style confirmation; Phase 2 batches the rest (≤3 concurrent); Phase 3 renders the closing page and assembles the deck.
• Visual consistency — a configurable style-lock paragraph is appended verbatim to every prompt.
• Narrative continuity — takeaway / role / next-question metadata flows across pages.
• Crash-resume — .progress.json is written after every page; restarts skip finished pages.
• Single-page replace — regenerate any page and swap it into the existing .pptx without touching the others.
• Provider-agnostic — "image2" is a code name; point it at any OpenAI-compatible text-to-image API.

---

Repository layout

image2-ppt-skill/
├── README.md                     # this file
├── README.zh-CN.md               # 中文说明
├── LICENSE                       # MIT
├── skill.md                      # ★ agent-execution instructions (Chinese; drives the orchestrator)
├── requirements.txt
├── config/
│   └── settings.example.yaml     # copy to settings.yaml and fill in your endpoint/key
├── scripts/
│   └── ppt_tool.py               # CLI: scan / generate / assemble / regenerate
└── examples/                     # sample per-page design specs (input format demo)
    ├── P01_封面_v1.md
    ├── P02_目录_v1.md
    └── P03_内容页_v1.md

---

Quick start

1. Install dependencies

pip install -r requirements.txt

2. Configure your image API

cp config/settings.example.yaml config/settings.yaml

Edit config/settings.yaml:

image2_api:
  endpoint: "https://your-provider.example.com/v1/text-to-image"  # your image API URL
  api_key: "${IMAGE2_API_KEY}"                                    # env-var placeholder

Then export the real key (never commit it):

export IMAGE2_API_KEY=sk-xxxx

settings.yaml is git-ignored. Keep the placeholder in the committed settings.example.yaml.

3. Prepare per-page design specs

You need one .md per slide, named P{page}_{title}_v{version}.md, each containing a metadata table plus an ## image2 视觉生成 Prompt section. See examples/ for the exact format.

4. Run it

CLI-only mode — test the pipeline manually:

# Parse a folder of page-design specs and initialize progress
python scripts/ppt_tool.py scan examples/

# Generate one page's slide image
python scripts/ppt_tool.py generate --md-file examples/P01_封面_v1.md --output-dir out/images/

# Assemble all done pages into a .pptx
python scripts/ppt_tool.py assemble --images-dir out/images/ --progress-file .progress.json --output out/deck.pptx

# Regenerate one page and replace it inside the deck
python scripts/ppt_tool.py regenerate --md-file examples/P03_内容页_v1.md --page-num 3 --pptx-path out/deck.pptx --output-dir out/images/

Agent-orchestrated mode — the full phased workflow (style confirmation, batching, resume, single-page replace) is defined in skill.md. Provide it to your coding agent (e.g. Claude Code) and ask it to follow the phases:

Please follow skill.md and turn the design specs in <folder> into a PPT.

---

How a prompt is composed

Every request sent to the image API is three parts concatenated:

{image2 prompt from the .md}      ← extracted verbatim, never rewritten
───────────────────────────────
{global style-lock block}         ← from config/settings.yaml, locks visual consistency
───────────────────────────────
{page narrative context}          ← role / previous takeaway / next question

Rationale: the per-page .md already contains a compiled, self-contained image prompt; sending the whole spec would just add noise.

---

CLI reference

Command	Purpose
scan <md_directory>	Parse page-design .md files, list metadata, emit progress-init JSON
generate --md-file … --output-dir …	Render one page's slide image
assemble --images-dir … --progress-file … --output …	Build the .pptx from done pages
regenerate --md-file … --page-num N --pptx-path … --output-dir …	Re-render one page and replace it in the deck

Run python scripts/ppt_tool.py --help for full options.

---

Notes & disclaimer

• This project is not affiliated with any image-generation provider. "image2" is an internal code name used here as a generic placeholder for the text-to-image API you configure.
• The upstream page-design step (which produces the per-page .md specs) is not part of this repository — any tool that emits the documented schema works. examples/ shows the format.
• Generated slide images and the assembled deck are your responsibility. Review output for factual and brand accuracy before distribution.
• Always supply the API key via environment variable or a git-ignored local config.

License

MIT