ppt-anything

name	ppt-anything
description	Use when creating illustrated PPT / infographic slide decks that tell a continuous story about a topic (tech sharing, onboarding, concept walkthrough, lesson recap, 萌系分享图, 故事 slide). Triggered by "做一套 PPT 讲 xxx", "生成故事图讲 xxx", "用萌系/日漫风做 xxx 分享图", "做一套故事 slide", or direct /ppt-anything invocation.

ppt-anything

Generate a cohesive series of anime-chibi-style illustrated infographic slides that tell a story about a user-provided topic. Default aesthetic: SD chibi Japanese anime characters + clean infographic layout + pinpoint-accurate Chinese text. (Users can override the style explicitly; otherwise this is what they get.)

Core principle — content is the hero

The content is the main subject. Characters, poses, scenes, and decorations exist to make the content come alive — not to steal attention from it.

Read hierarchy per slide: 内容清晰可读 > 人物表达情绪 > 装饰点缀氛围. If a pose or decoration makes the viewer read slower, it's a bug. Whenever a choice competes — e.g., a bigger character portrait vs. a larger title — the content wins.

Everything downstream (character selection, reference-image discipline, layout rotation, pose vocabulary, decoration density) is a supporting mechanism. When one of those mechanisms pulls focus from the copy or the beat, it's malfunctioning — cut or shrink it.

Runtime layout (must know)

This skill is self-contained — no external sub-skills required.

Path	Role
~/.claude/skills/ppt-anything/tools/generate-image.py	Single image client. Default: Google Gemini official. Also supports Gemini-compatible bridges and OpenAI-compatible bridges. Run --help for provider options.
~/.claude/skills/ppt-anything/tools/batch-generate.py	Batch parallel image client. Reads JSON manifest, all slides generated simultaneously, failed slides auto-retry. Used by fast mode.
~/.ppt-anything/providers/<name>.toml	API credentials ([auth].api_key + [auth].base_url + [auth].docs_url + [auth].auth_style). Source of truth for keys. The agent never reads this file directly — generate-image.py does.
~/.ppt-anything/characters/<slug>/<slug>.{md,png}	Character library. Skill reads from here at runtime.
~/.ppt-anything/styles/<style-name>/	Style packs. Default anime-chibi-default/ ships with the skill.
~/.ppt-anything/demo/<YYYY-MM-DD>-<HHMM>-<slug>/	Auto-archive of every generated deck (outline + slides + html + meta). Includes time to prevent same-day collisions.
~/.claude/skills/ppt-anything/tools/build-html-ppt-external.py	Default HTML packager (WebP external refs, ~3KB shell).
~/.claude/skills/ppt-anything/tools/build-html-ppt.py	Single-file HTML packager (base64, only for WeChat/email use cases).

Provider iron rules (read before first run)

1. Agent does NOT read provider toml files. The toml stores api_key. Reading it = pulling the key into the agent's conversation context (cached, persisted in memory systems, replayed across turns, leaked between agents). To check whether config is ready, call generate-image.py and let it fail with a clear status — its error messages tell you which field is missing without exposing the key. Never cat / Read any *.toml file body. ls of the filenames is fine; contents are not.

2. Handing api_key / base_url to the agent is a risk operation. When the user's path is "I'll edit the toml myself", the agent sees zero key bytes — safe. When the user's path is "agent, please write the toml for me", the agent must explicitly warn ("your key will enter my context, the recommended path is option A") and require a second confirmation before touching the key string.

3. Agents that register a new provider MUST verify connectivity. Writing the toml is not enough — call tools/register-provider.py which uses the cheapest model + smallest prompt to actually round-trip one image, and only marks verified=true when that succeeds. A failed verify means the toml goes back to verified=false and the user is told what to check.

First-run wizard (no provider configured yet)

Trigger (mandatory, BEFORE asking the user any briefing question): The agent runs ~/.claude/skills/ppt-anything/tools/check-providers.py. The script reads provider tomls internally and outputs a key-free summary on stdout:

• Exit 0 + READY: <names> → at least one provider is configured. Note the names; surface them in Step 2 as the choices for "which provider".
• Exit 1 + NEED-CONFIG: ... → STOP. Open the conversation below before doing anything else.

The agent does NOT cat / Read any toml. check-providers.py does the reading; agent only sees ok/incomplete summaries.

"I notice ppt-anything has no usable provider configured yet. Two paths:

Path 1 — Google official (recommended) The shipped ~/.ppt-anything/providers/google.toml already has base_url / docs_url / auth_style filled with the official values. You only need to:

1. Get a Gemini API key from https://aistudio.google.com/app/apikey
2. Open google.toml in your editor and paste it into [auth].api_key

Strongly recommended. I never touch your key bytes.

Path 2 — Third-party bridge (risky) If you've subscribed to some third-party Gemini-shape or OpenAI-image-compatible bridge, I can write the toml for you. You'd give me:

• base_url (gateway URL)
• api_key (giving this to me means it enters my context — caching / memory / multi-agent transcript leakage are all on the table)
• docs_url (I'll WebFetch it to confirm request/response shape)
• auth_style (google for X-Goog-Api-Key, bearer for OpenAI-style Authorization)

Reconfirm: if you go Path 2, I will see your key. If you'd rather I never see it, switch to Path 1 — cp google.toml my-bridge.toml, edit it yourself.

Which path? (1 / 2 / something I haven't listed)"

If the user picks Path 2, the agent runs the connectivity self-test via tools/register-provider.py (which writes the toml AND verifies it round-trips one image before returning). See § Setup tool below.

generate-image.py reads credentials from ~/.ppt-anything/providers/<name>.toml itself. The agent does not need to involve itself — call the script and let it handle the secret.

Setup tool — register-provider.py

The agent uses this when registering ANY non-default provider. It:

1. Writes ~/.ppt-anything/providers/<name>.toml from the user-supplied fields.
2. Generates one tiny image via gemini-2.5-flash-image (~$0.04, ~10s) to verify base_url + api_key + auth_style actually work end-to-end.
3. Marks [provider].verified = true only on success. On failure, the toml is left with verified = false and the script exits non-zero so the agent flags the user to check the offending field.

Invocation pattern (agent-side; key never goes on the command line — pipe via stdin):

echo "$USER_KEY" | ~/.claude/skills/ppt-anything/tools/register-provider.py \
  --name my-bridge \
  --base-url https://example.com \
  --auth-style bearer \
  --docs-url https://example.com/docs \
  --key-stdin

If the user prefers Path 1 (Google official, fill the key themselves), the agent does NOT run register-provider.py — it tells them to edit google.toml directly, then they re-invoke the skill and the agent verifies on first generation.

When to use

• User asks for a story-telling illustrated slide deck / 故事 PPT / 萌系分享图 / 绘本 slide
• Topic needs multiple slides to walk through (onboarding, tech talk, concept recap, workflow explanation)
• User wants anime-chibi aesthetic combined with Chinese text

When NOT to use

• Single standalone picture with no slide context → use generate-image directly
• Realistic / photographic / non-anime style → wrong skill
• Only a cover image needed → generate-image with one prompt is faster

Workflow

0. Provider readiness gate (run BEFORE everything else, including library snapshot). Run ~/.claude/skills/ppt-anything/tools/check-providers.py. Read the stdout summary:

   • Exit 0 → at least one provider is READY or verified. Remember the list; you'll surface it as Step 2's provider-choice options. Proceed to Step 1.
   • Exit 1 → no provider usable. DO NOT proceed to briefing. Surface the problem to the user and run the first-run wizard (§ First-run wizard above): walk them through Path 1 (self-fill google.toml) or Path 2 (tools/register-provider.py for a bridge). Resume Step 1 only after the user has finished setup AND a re-run of check-providers.py exits 0.

   Anti-pattern (do NOT do this): don't proceed to briefing/outline/generation when the gate fails — you'll waste user time + collect a brief that can't be executed because the rail isn't ready. The gate is the FIRST thing in this skill, not an afterthought triggered by a 401 mid-flow.

1. Library snapshot, briefing second. Before asking the user any open-ended brief questions (audience / register / slide count / character preference / etc.), do these reads in parallel:

   • ls ~/.ppt-anything/characters/ — list available character slugs
   • ls ~/.ppt-anything/styles/ — list available style packs
   • ls ~/.ppt-anything/providers/ — list provider toml files (filenames only; do NOT cat them — agent never reads provider toml)

   For each character slug, Read the character's <slug>.md profile to know what it looks like (you'll need this to judge fit). For each style, glance at <style>/manifest.md if it exists.

   Then open the briefing with the user — lead with what's actually in the library, not a generic 5-question form. Example shape:

   "库里现在有：橙橙(暖橙水滴 · 冲劲) + 蓝蓝(深蓝水滴 · 稳健搭子)、anime-chibi-default 风格、[已配置的 provider 列表]。

   你想做的是 [回放用户主题]。这俩水滴吉祥物天然配 [topic-fit 评估]。

   我需要你定的：[只问 1-2 个 truly missing 的关键点 — 例如基调、张数、是否要新建角色]"

   Anti-pattern (do NOT do this): Send a 5-question form (视角 / 切片 / 基调 / 角色 / 张数) without first surfacing what's available. The library constrains feasibility; ignoring it makes briefing rounds blow up.

   Topic-character fit judgment: if the user's topic obviously needs a kind of character the library can't serve (e.g. user wants a 写实校园怀旧, library only has abstract OC water droplets), proactively flag that mismatch in the briefing — offer two paths: (a) accept abstract symbolic handling with the existing characters, (b) add a new character now (Branch B/C of step 2). Don't proceed with a topic that can't work and discover it 3 rounds later.

Quality gates (self-check every run)

• T1: Reused a character from the library without re-searching (when the character was already on disk)
• T2: New character got a profile written BEFORE generation, not after
• T2b: Every character in the deck has a local reference image on disk (~/.ppt-anything/characters/<slug>/<slug>.<ext>) AND Claude has Read it (vision input) at least once this session. No text-only character goes into generation.
• T3: Full outline approved by user before the first generate.py call
• T4: EVERY generate.py call passes the character reference image(s) as --ref; slides 2+ ALSO pass the previous slide as --ref. No slide relies on daisy-chained previous slides alone.
• T5: Each slide uses a DIFFERENT layout from the previous slide (no 5× identical ribbon-banner template)
• T6: Each slide uses a DIFFERENT character pose from the previous slide
• T7: 生成模式被显式问过 — 高质量(顺序+每张看图复盘) vs 快速(batch-generate.py 全量并行+失败自动重试)。没有静默默认。高质量模式下每张生成完 AI 都 Read 过该图; 快速模式下通过 batch-generate.py 全部同时发出, 失败自动重试, 不中途 Read。
• T11: provider 选定后, model + 分辨率都用了 provider 范围内的顶配。具体参数参考 generate-image.py --help。降配只在用户明示"省钱/草稿/不敏感"时触发。
• T8: Every element on every slide earns its place — no filler character / decoration / sentence added to meet a quota. If asked "why is this here?" you can answer with a story reason, not a rule reason.
• T9: Design intent was articulated per slide and shown to the user BEFORE any generation — covering beat, layout choice, pose choice, copy, decorations (with reasoning)
• T10 (content-first sanity check): On each finished slide, the viewer's eye lands on the title/copy first, then the character, then the decorations. If a character or decoration is stealing the scene, shrink or reposition — characters serve the content, not the other way around.

Failing any gate = restart from the failing step. Do not patch on top of a broken gate.

Style rules

See ~/.ppt-anything/styles/<active-style>/style_guide.md. Default aesthetic: SD chibi 2.5-head-body characters, hand-painted watercolor finish, clean pastel infographic layout, LXGW WenKai Chinese font, content-first hierarchy. Key sub-sections to consult:

• § 3 Character pose vocabulary — pick a fresh pose each slide; avoid mid-action poses and abstract props (§ 3 Pose traps)
• § 4 Layout variation — pick a different layout each slide; match layout to beat shape (§ 4 Layout × beat fit); for memory / emotion / lived-experience beats, consider a custom scene over A–H (§ 4 Scene-ify)
• § 6 Background — clean, restrained, no "magical forest" filler
• § 7 Decoration density — context decides, not a number; flow/timeline slides = near-zero extras
• § 12 No emoji, ever (hard rule) — zero Unicode emoji in any text slot; describe marks as painted motifs
• § 13 Chinese glyph clarity (soft hint) — keep lines short, split long phrases across two lines

Deviate only when the user explicitly requests a different style. Drift within a single deck is the #1 failure mode.

Prompt template

See ~/.ppt-anything/styles/<active-style>/prompt_template.md. All slots are <<ALL_CAPS>>. Never ship to generate.py with a slot still in place.

Character library

See ~/.ppt-anything/characters/README.md for profile schema, the mandatory reference-image rule, and the two branches (public vs user-provided). Every new character — whether researched online or given to you by the user — must be persisted as BOTH a profile .md AND a local image file. Text description without a verified image = character drift in production.

Common mistakes

Mistake	Why bad	Fix
Generating images before showing outline	Burns money on wrong direction	Gate T3 is mandatory
Forgetting --ref from slide 2 onward	Characters drift between slides	Check Gate T4 before each call
用户选快速模式但 agent 逐张串行调用 generate-image.py	浪费用户时间, 快速模式的意义就是并行	快速模式必须用 batch-generate.py 全量并行, 失败自动重试 (T7)
没问用户模式 (高质量/快速) 直接开始生成 — 即使是"安全的"顺序也违规	把 钱 + 时间 的 tradeoff 从用户手里拿走。用户想快你给慢, 用户想稳你给快批崩了。"顺序很安全所以不用问"是最危险的借口, 因为它把 AI 的偏好包装成默认	T7 + Step 2 Generation mode: 模式问询是 slide 1 之前的硬门, 必须问。"我 default 顺序" / "用户没说我猜稳" / "outline 已经过了" 全部不算。问的时候必须把"高质量=顺序+我看图"和"快速=批量+不看图"都摆上, 让用户拍
用户说一个 style 方向 (科技风/复古风/商务风/赛博朋克), 库里没有该 pack, AI 回 "我对你的话有 2/3 种理解, 是哪个?"	把推断成本甩回给用户 — 用户已经说清楚他要那个 style 了。库 miss = 该 BUILD 新 pack 的信号, 不是该让用户解释一遍他刚说过的话。"我有 N 种理解" 框架在装认真, 实际是把决策推给用户	Step 1 Style-library miss judgment: 直接说 "库里没这个 style, 我去建新 pack — 在这个 style 内部你拍方向 A/B/C?" 框架是 "我在建, 给我方向", 不是 "我搞不懂你说啥"。建 pack (manifest+style_guide+prompt_template+outline_template) 是正常分支不是异常
注册 / 选定 provider 后用 generate-image.py 的硬编码默认而不是 provider 顶配	用户为顶配 provider 付了钱却只拿中等画质。"水彩 2K 够用" / "我不知道 max 是多少所以 2K 安全" / "flash 便宜先试试" 都是把 AI 偏好包装成谨慎默认, 实际吃用户预算	T11 + Step 2: 跑 generate-image.py --help 确认 provider 顶配参数, 用顶配。降配只在用户明示触发
Auto-picking a provider when multiple toml exist	User pays for the wrong rail / wrong quality / wrong key	If ls ~/.ppt-anything/providers/*.toml shows >1 entry, ASK the user which to use — do not silently default
Same layout on every slide	Monotonous deck, reader disengages	Vary layouts per ~/.ppt-anything/styles/<active-style>/style_guide.md § Layout variation (T5)
Same character pose every slide (e.g. "holding notebook")	Dead deck, no motion	Pick fresh pose from vocabulary per slide (T6)
Padding a slide with filler (extra characters / decorations / copy) to "look rich"	Dilutes the main message; filler ≠ richness	Every element earns its place or gets dropped (T8)
Character in the visual center with content pushed to the side	Character steals focus from the message	Characters serve the story — place content at the visual anchor, characters frame/support