JuneYaooo/gpt-image2-ppt-skills

gpt-image2-ppt -- Generate PPT Using gpt-image-2

Feed a Markdown outline (or slides_plan.json) + a visual style directly to the OpenAI Images API (gpt-image-2), generate slides page by page, and finally package them into a 16:9 .pptx.

Available Styles

Style ID	One-Liner Positioning	Use Case
gradient-glass	Apple Vision OS / Spatial Glass	AI product launches, tech talks, creative proposals
clean-tech-blue	Stripe / Linear level blue-white	Fundraising roadshows, business plans, corporate strategy
vector-illustration	Retro vector illustration + black outline	Education & training, brand storytelling, community sharing
editorial-mono	Kinfolk / Monocle editorial design	Brand launches, cultural interviews, book sharing
dark-aurora	Linear / Vercel dark neon	AI products, developer tools, tech talks
risograph	Risograph duotone printing + halftone texture	Creative studios, cultural & creative brands, indie zines
japanese-wabi	Muji / Kenya Hara-style wabi-sabi	Tea ceremony, lifestyle, luxury goods, cultural lectures
swiss-grid	Bauhaus / Vignelli international typographic grid	Academic reports, museum exhibitions, formal presentations
hand-sketch	Sketchnote / whiteboard hand-drawn	Workshops, product brainstorming, training
y2k-chrome	Y2K millennial liquid metal + butterfly stickers	Streetwear, entertainment, brand collaborations, Gen Z marketing
abstract-art-showcase	Black-white minimalism, art exhibition feel, oversized fonts juxtaposed with abstract visuals	Art curation, portfolios, brand tone display
coal-industry-business-company-profile	Industrial brown-black, heavy headings, structural lines, bold icons	Energy, manufacturing, heavy asset company profiles
college-candy-aesthetics-infographics	Candy colors, campus feel, rounded infographics and light decorations	Education, campus events, light data science popularization
creative-agency	Creative agency vibe, strong visual collage, distinct typographic rhythm	Agency proposals, brand pitches, creative reports
culinary-innovation	Culinary innovation feel, food photography, warm color blocks, magazine-style layout	Food & beverage brands, food innovation, menu/new product launches
data-science-consulting	Data consulting blue-gray, modular layout, charts and technical information hierarchy	Data analysis, AI consulting, enterprise digitization
mindfulness-in-the-classroom-breathing-techniques	Soft mental health color palette, white space, rounded blocks, quiet illustration feel	Mental health, classroom activities, breathing exercise courses
mind-maps-workshop-professional	Professional workshop style, mind map nodes, clear process structure	Training workshops, methodologies, team co-creation
meeting-agenda	Meeting agenda feel, clean grid, strong information grouping, business headings	Regular meetings, project sync, management reports
investment-company-business-plan	Investment firm quality, deep-light contrast, steady business typography	Investment plans, fund introductions, business plans
indigenous-cultures	Cultural patterns, natural colors, handcrafted texture, narrative composition	Cultural courses, historical topics, public education
health-disparities-and-social-determinants-of-health-doctor-of-philosophy-phd-in-health-behavior-and-health-education	Public health academic style, rational grid, soft medical colors, thesis-level hierarchy	Medical thesis defense, public health reports, educational research
geometric-duotone-thesis	Two-tone geometric, thesis defense feel, angled graphics, strong headings	Academic defense, research reports, chapter-style content
geometric-clinical-case	Geometric medical style, calm colors, case cards, clear column layout	Clinical cases, medical training, diagnosis & treatment reports
geometric-business	Business geometric blocks, steady blue-green tones, concise chart language	Business plans, team reports, product strategy
formal-lavender-portfolio	Formal lavender feel, portfolio white space, elegant thin lines, soft typography	Personal portfolio, design resume, professional showcase
flowery	Floral decoration, soft color blocks, romantic yet orderly layout	Lifestyle, female-oriented brands, event introductions
first-impressions	First impressions theme, strong cover visual, dramatic relationship between people/titles	Interview training, personal branding, communication courses
final-year-project-thesis-defense	Graduation project defense, academic grid, clear chapters and data pages	Graduation defense, project conclusion, research showcases
fashion-business-consulting-toolkit-aesthetic	Fashion consulting feel, high-end collage, magazine layout, neutral colors	Fashion business, brand consulting, trend reports
economic-impact-of-coronavirus	Economic impact report style, serious infographics, calm colors, data storytelling	Macroeconomics, policy analysis, risk reports
eco-green-business-plan	Sage green, natural material photography, eco-friendly business and minimalist split-screen	Sustainable business, green brands, healthy lifestyle

All available styles are uniformly placed under styles/ and grouped by source. Usage is identical: initial/ contains the first 10 sets, featured/ contains 22 curated sets, and xiamulingzi/ contains 233 sets from designer @夏目玲子. Directory index at styles/README.md; curated style cover showcases at docs/distilled-styles.md.

Style selection principle: First, choose the closest style in styles/ based on the content scenario. For tech content, prioritize dark-aurora / gradient-glass / data-science-consulting. For business, prioritize clean-tech-blue / editorial-mono / eco-green-business-plan / investment-company-business-plan. For culture/lifestyle, prioritize japanese-wabi / vector-illustration / culinary-innovation / flowery. For academic, prioritize swiss-grid / geometric-duotone-thesis / final-year-project-thesis-defense. For workshops and training, prioritize hand-sketch / mind-maps-workshop-professional / mindfulness-in-the-classroom-breathing-techniques.

Scenario Recipes (Optional Starting Templates)

examples/ is not a new skill nor a runtime requirement. It is a scenario starting template library for this skill, used to help the agent write the first version of slides_plan.md faster when the user only gives vague requirements.

Trigger Rules:

• If the user has already provided a complete outline / complete slides_plan.md / complete slides_plan.json, do not use a recipe. Proceed directly with the generation flow based on user content.
• If the user only says "make a product launch PPT / fundraising roadshow / weekly report / course material / thesis defense / book sharing" or other common scenarios, and has not given a clear page structure, first check if examples/ has a matching recipe.
• The recipe serves only as a structural reference: read examples/<id>/recipe.md to understand the scenario, recommended style, and notes, then reference the page order structure of examples/<id>/slides_plan.md and rewrite it with the user's own topic and content.
• Do not directly use the fictional products, companies, projects, or data from the examples as the user's final work. They must be replaced with information provided by the user, or explicitly marked as placeholder content pending user confirmation.
• If the user provides real images, logos, screenshots, paper figures, or product UI, handle them according to the "external real image placement" rules. The recipe is only for content structure and does not replace the asset fidelity process.

Current built-in recipes:

User Scenario	Recipe Directory	Recommended Style
Product launch, new feature release, AI product introduction	examples/product-launch/	gradient-glass
Fundraising roadshow, business plan, investor presentation	examples/investor-pitch/	clean-tech-blue
Project weekly report, monthly report, regular sync	examples/weekly-report/	meeting-agenda
Course materials, training, knowledge popularization	examples/courseware/	vector-illustration
Thesis defense, graduation project defense, project conclusion	examples/thesis-defense/	final-year-project-thesis-defense
Book sharing, cultural interview, opinion sharing	examples/book-sharing/	editorial-mono

How to use:

1. Determine if the user's request matches a recipe.
2. Read the corresponding recipe.md and slides_plan.md.
3. Based on the user's topic, write a new slides_plan.md. Do not modify the original recipe source files directly.
4. Confirm the number of pages, title, and key content for each page with the user.
5. After user confirmation, run md_to_plan.py to convert to JSON, and proceed with the specified style or template cloning process.

Layout Bank Sidecar for Built-in Styles (Only Running Format)

Built-in styles use a dual-file structure: "MD for humans, JSON for machines":

styles/<collection>/<style-id>.md            # Style description, design tokens, base prompts
styles/<collection>/<style-id>.layouts.json  # Required; per-page layout bank for automatic page type allocation

generate_ppt.py treats the homonymous .layouts.json as a RuntimeProfile without reference images: it uses assign_layouts() to allocate different layouts, writes visual_signature / content_capacity / best_for / avoid_for / variation_tags into the prompt, and records the matched layout's condensed information into metadata.json.

Currently, all styles/**/*.md must be accompanied by a .layouts.json file of the same name in the same directory. Old styles with only Markdown and no sidecar will error out directly before image generation, no longer silently falling back to the old Prompt. Migrate them to the paired format first. When distilling public templates or adding new built-in styles in the future, both the JSON sidecar and the Markdown must be produced; do not compress multi-page layouts into a single MD paragraph describing a "layout system."

Unified RuntimeProfile Runtime Kernel

Both strict template cloning and structured style sidecar are first compiled into the same RuntimeProfile, then uniformly processed through assign_layouts(), page Profile attachment, prompt compilation, and metadata recording. The entry point adapters only retain necessary differences:

• template-clone: Comes from --template-profile or template vision analysis; layouts can carry reference_image; only --template-strict actually passes them into image generation.
• distilled-style: Comes from <style>.md + <style>.layouts.json; uses content routing and multiple layouts, does not depend on original template images.

The RuntimeProfile uniformly records source_kind, a fixed prompt_strategy=layout-fields, layouts, and capabilities (routing / evidence / reference / portability). The priority is fixed as: valid template Profile > style RuntimeProfile; if template analysis has no layouts, it must genuinely fall back to structured style, not just print a hint. The runtime no longer includes legacy-freeform or synthetic layout branches.

Template Cloning Mode

Directly provide the skill with a .pptx template; all subsequent slides will mimic this template.

# One-liner: automatic rendering + template analysis + image generation. Requires a usable PPTX rendering backend on this machine.
python3 scripts/generate_ppt.py \
  --plan slides_plan.json \
  --template-pptx ./company-template.pptx \
  --template-strict

--template-strict means every page's corresponding template page is fed as an image reference to gpt-image-2, offering the highest fidelity.

Template Rendering: No PowerPoint Needed on This Machine

The skill includes render_template.py, which automatically renders a .pptx into per-page PNGs, saved to <cwd>/template_renders/<stem>/page-NN.png.

Agent Pre-checks (Mandatory for Template Cloning)

Before running any --template-pptx command, you must first check if this machine has a workable PPTX rendering backend.

How to check:

• Preferred: Run python3 scripts/render_template.py --check in the skill directory. It verifies the backend is truly executable, not just that the path exists.
• macOS: First check for /Applications/Keynote.app and that AppleScript is executable; otherwise check libreoffice --version || soffice --version.
• Windows: First check if the local PowerPoint COM can be started; otherwise check libreoffice --version / soffice --version.
• Linux / Compatibility layers: Check libreoffice --version || soffice --version; do not rely solely on which.

Note: HarmonyOS / Termux / containers / special architecture environments might look like Linux, but you cannot assume a Linux aarch64 LibreOffice binary will run. The actual execution result of render_template.py --check or soffice --version should be the authority. Do not make aspose-slides the default fallback; it often has no installable wheel in many mobile/special Python environments.

If no usable backend is found, first inform the user that template rendering requires a working LibreOffice installation, or they can manually export each template page as page-01.png, page-02.png, etc. on their desktop and pass them via --template-images. Optional installation commands:

Platform	Installation Command
Windows	winget install LibreOffice.LibreOffice
macOS	brew install --cask libreoffice
Linux (Debian/Ubuntu)	sudo apt-get install -y libreoffice
Linux (Fedora/RHEL)	sudo dnf install -y libreoffice
Linux (Arch)	sudo pacman -S --noconfirm libreoffice-fresh

After installation, check again to confirm a valid rendering backend exists before proceeding.

Note: On Windows, winget is built into Win10/11 and will pop up a UAC confirmation dialog requiring user approval. On macOS, brew requires Homebrew to be installed first.

render_template.py automatically selects the rendering backend by priority:

1. Windows: PowerPoint COM (preferred if Office is installed locally, outputs PNG directly, skips the PDF step) > LibreOffice
2. macOS: Keynote AppleScript (preferred if Keynote is installed locally, outputs PNG directly) > LibreOffice
3. Linux / Compatibility layers: Uses a command confirmed executable via --version (LibreOffice / soffice)
4. PDF -> PNG uses pymupdf (in requirements); if not installed, falls back to pdf2image + poppler

If you run generate_ppt.py --template-pptx ... and omit --template-images, it will automatically trigger a render once. You can also manually render once first:

python3 scripts/render_template.py company-template.pptx
# -> <cwd>/template_renders/company_template/page-01.png ... page-NN.png

Two-Level Cache for Template Mimicking

Asset	Path	Purpose
Template per-page PNGs	<cwd>/template_renders/<stem>/page-NN.png	Local rendering backend renders once, reused long-term
Template style analysis	<cwd>/template_cache/<sha256>.json or manually written template_profile.json	Generated by the multimodal agent itself via image viewing; only text-only agents need an external vision backend
Output products	<cwd>/outputs/<timestamp>/	New directory for each run

All three are under the caller's cwd, naturally in sync with the project. It is recommended to add template_renders/, template_cache/, and outputs/ to your project's .gitignore.

Template image analysis (let the agent decide if VISION_* needs configuration):

• If the current code agent is itself a multimodal model (e.g., Claude Code's multimodal Claude, Codex's multimodal GPT): No extra VISION_* configuration is needed. The agent directly reads template_renders/<stem>/page-*.png, generates template_profile.json following the TemplateProfile structure in template_analyzer.py, and then passes it to generate_ppt.py with --template-profile template_profile.json. To use with --template-strict, each layout must include reference_image (the absolute or accessible path to the template PNG).
• If the current code agent is a text-only model (e.g., only connects to a DeepSeek text model): It cannot view template screenshots. In this case, you need to additionally configure VISION_BASE_URL / VISION_API_KEY / VISION_MODEL_NAME so that template_analyzer.py can call an independent OpenAI-compatible multimodal endpoint for template analysis.

Vision analysis and image generation via gpt-image-2 are always decoupled—switching vision providers does not affect the image generation path.

Installation

git clone [email protected]:JuneYaooo/gpt-image2-ppt-skills.git
cd gpt-image2-ppt-skills
bash install_as_skill.sh --target claude   # Claude Code
# or
bash install_as_skill.sh --target codex    # Codex
# Keys required for direct API connection are preferably injected via agent configuration / system environment variables

Environment Variable Injection (For Direct API Connection)

Do not write this skill's keys into the calling project's root .env file. Also, do not read generic .env files from the user's project for image generation. It is recommended to inject environment variables according to the agent framework's standard method:

• General / CI / Server: Use system environment variables, Docker Compose environment / env_file, Kubernetes Secrets, CI Secrets, etc.
• Claude Code: Use the user-level ~/.claude/settings.json or project-level .claude/settings.local.json to inject environment variables; command-line environment variables take the highest priority.
• OpenClaw / Custom Agent: Use the framework configuration's apiKey / env reference to refer to system environment variables, avoiding writing keys in plain text into the project configuration.
• Local standalone CLI fallback: You can set GPT_IMAGE2_PPT_ENV=/path/to/private.env, or use a .env file in the skill installation directory. This is only a fallback method, not the main one, and should not be the business project's .env.

Direct API connection requires these variables:

OPENAI_BASE_URL=https://api.openai.com    # Or any OpenAI-compatible relay
OPENAI_API_KEY=sk-...
GPT_IMAGE_MODEL_NAME=gpt-image-2
GPT_IMAGE_QUALITY=high                     # low / medium / high / auto

# Optional: Vision analysis backend for template cloning mode.
# Multimodal agents / native Codex can view images themselves to generate --template-profile, so this group is not needed.
# Only text-only agents (e.g., DeepSeek text model) require this external group.
# No default endpoint is built-in; fill in a service you trust, otherwise leave it empty.
# VISION_BASE_URL=https://your-openai-compatible-relay.example.com/v1
# VISION_API_KEY=sk-...
# VISION_MODEL_NAME=gemini-3.1-pro-preview   # Or any multimodal SKU like gpt-4o / claude-3.5-sonnet

The configuration priority is fixed as: current process environment variables > platform-injected gpt-image2-ppt_* variables > GPT_IMAGE2_PPT_ENV / skill directory .env; JULING_GPT_IMAGE2_* variables only serve as a compatibility fallback when no corresponding OPENAI_* configuration is present, and will not override explicit configuration.

Security Notice: Scripts only read the current process environment, platform-injected gpt-image2-ppt_* variables, the explicit GPT_IMAGE2_PPT_ENV file, and the .env fallback in the skill installation directory. The script will not recursively read .env files from the caller's project directory upwards, preventing accidental ingestion of business project keys. python3 scripts/render_template.py --check will perform a minimal real transformation to verify the rendering backend.

If You Are a Codex Agent (Native image_generation Image Generation — Recommended)

If you yourself are Codex (the agent running this skill is Codex CLI / Codex TUI), and the current environment provides the image_generation tool and a ChatGPT login session, then do not use generate_ppt.py or --backend codex for image generation. Use the native tool to generate images directly, and only reuse this repository's markdown conversion / PPTX packaging logic.

Critical boundary: Python scripts run in a subprocess and do not have access to the current agent session's native tools. What generate_ppt.py --backend codex can do is only spawn another codex exec subprocess, letting another Codex do the image generation. It is not "reusing the current Codex's image_generation tool." Therefore, when the current agent can already generate images natively, the image generation action must be performed by the agent itself, not by generate_ppt.py.

How to Determine

If you have access to the image_generation tool and can generate images without manually configuring OPENAI_API_KEY—both conditions must be met to use the native path. If the current Codex session does not have this tool, treat it as a regular agent: use direct API connection, --backend codex as a fallback backend, or ask the user to provide the environment.

Image Generation Flow (Codex Native Path)

1. Prepare Slide Data

If there is no slides_plan.json yet, first follow steps 2-3 of the "Generation Flow" below: write slides_plan.md → python3 scripts/md_to_plan.py ... to convert to JSON.

2. Use the Unified Runtime to Prepare Prompts

Do not manually replicate generate_prompt(). Run --prepare-only so that the direct API connection and Codex native path share the same RuntimeProfile, layout routing, and prompt compiler:

python3 scripts/generate_ppt.py \
  --plan slides_plan.json \
  --style styles/<collection>/<id>.md \
  --prepare-only \
  --output outputs/<timestamp>

This command does not call the image API or package the PPTX; it generates prompts.json, per-page prompt text files, and metadata.json. For a single-page smoke test, also pass --slides 1.

3. Read the Compiled Results for Each Page

From outputs/<timestamp>/prompts.json, read each page's prompt, reference_image, asset_reference_image, and layout_id. Do not manually reconstruct a Prompt from the Markdown, as this bypasses the structured layout bank.

4. Call the image_generation Tool to Generate Images

For each page, call your image_generation tool:

• prompt: The fully compiled prompt for that page from prompts.json
• output_format: png
• If reference_image / asset_reference_image is recorded, pass them as image references in the original order
• Save the returned image to outputs/<timestamp>/images/slide-NN.png (NN is the two-digit page number)

Concurrency is possible (recommended ≤4 concurrent requests to avoid rate limiting).

5. Package into PPTX

If this deck has no external real image objects, the following simple full-page PNG packaging can be used. If any page has external_image / image_overlay / external_image_placeholder pointing to a real image, do not use this simple packaging snippet; otherwise, the real image will be merged into the full-page background PNG, preventing the user from selecting and moving it independently in PowerPoint. In that case, you must use generate_ppt.py's standard packaging logic, or call generate_pptx(..., metadata=metadata) within an existing session to place the real image as an independent picture object on top of the background.

python3 -c "
from pptx import Presentation
from pptx.util import Inches
prs = Presentation()
prs.slide_width = Inches(13.333)
prs.slide_height = Inches(7.5)
blank = prs.slide_layouts[6]
import os, glob
for p in sorted(glob.glob('outputs/<timestamp>/images/slide-*.png')):
    slide = prs.slides.add_slide(blank)
    slide.shapes.add_picture(p, 0, 0, width=prs.slide_width, height=prs.slide_height)
prs.save('outputs/<timestamp>/<title>.pptx')
print('done')
"

The correct PPTX structure for pages with external real images should be:

• Layer 1: images/slide-XX.png as the full-page background image (including model-generated background and text).
• Layer 2: The real image pointed to by source as an independent PPT picture object, positioned on the background according to slide_spec coordinates, allowing selection, dragging, and scaling within PowerPoint.

Template Cloning Mode (Codex Native Path)

You yourself are a multimodal agent—directly Read each template page PNG to extract the visual style, write it as template_profile.json (schema is TemplateProfile in template_analyzer.py, each layout must include reference_image), then use --template-profile template_profile.json --template-strict --prepare-only to compile each page's prompt and reference; do not manually choose another prompt assembly logic.

No VISION_* configuration needed—you are the vision.

Distinction from "--backend codex" Below

	Native Path (This Section)	--backend codex
Use Case	You are the Codex agent	You are Claude Code / other agent, borrowing the local codex CLI
Invocation	Directly calls the image_generation tool	Spawns a codex exec --full-auto subprocess
Image Generation Depth	1

...

[The rest of the SKILL.md is truncated due to length. Please refer to the original document for the complete content.]