--- name: paperbanana-slide-deck description: Use when user wants to create a full slide deck or presentation using PaperBanana image generation, OR modify/regenerate an existing PaperBanana slide deck, OR build an editable PPTX with native text/tables/charts. Triggers on "make slides", "create presentation", "PPT", "slide deck", "regenerate slides", "update slides", "paperbanana slides", "editable PPTX", "editable slides". Also triggers when user has an existing slide-deck directory with outline.md and wants to regenerate images or make changes. This is the PRIMARY slide deck skill — always prefer over baoyu-slide-deck. ---

# PaperBanana Slide Deck

End-to-end slide deck creation and modification. Two deck modes (`image` and `editable`, chosen explicitly in Phase M), and within image mode two workflows: creating new decks from scratch, and regenerating existing decks after prompt edits.

**Image pipeline:** Content → Style Selection → Outline → Prompts → Image Generation → PPTX Merge **Editable pipeline:** Content → `slide-spec.json` (native text/table/chart/shape/line/group) → validate → build PPTX → render previews → Critic review → revise spec → rebuild

## Phase M: Deck mode selection

Record exactly one line in `deck-mode.txt`: `image` or `editable`.

- Use `editable` when the user asks to edit text/tables/charts/connectors in PowerPoint or explicitly asks for editable PPTX. - Use `image` when the user asks for generated full-slide artwork or preserves the existing PaperBanana image workflow. - If both are plausible, ask before generation. Do not infer from file presence. - `editable` requires `slide-spec.json`; a missing or invalid spec is an error. Never fall back to image mode while claiming editability.

## Mode Detection (image mode)

Within image mode, determine the workflow by checking the target directory:

| Condition | Mode | Start Phase | |-----------|------|-------------| | Target dir missing OR no `outline.md` | **New** | Phase R (full RDIV) | | Target dir has `outline.md` + `prompts/` | **Modify** | Phase I (generate + merge) |

In Modify mode, the user has already edited prompts or outline externally. Skip directly to Phase I.

## Dependencies

| Component | Role | Location | |-----------|------|----------| | `google-genai` SDK | Path B image generation | `pip install google-genai` | | PaperBanana CLI | Path A image generation | `python -m paperbanana.cli slide-batch` | | merge-to-pptx.ts | PPTX merge (image mode) | `plugins/paperbanana-slide-deck/scripts/merge-to-pptx.ts` | | build-deck.ts | Explicit `--mode image\|editable` router | `plugins/paperbanana-slide-deck/scripts/build-deck.ts` | | Editable renderer | `slide-spec.json` → native PPTX | `plugins/paperbanana-slide-deck/scripts/editable/` | | Style libraries | Style presets (4 sources, 150+) | See R1 for discovery paths | | Bun | Run build/merge scripts | `bun` |

## Editable Mode Workflow

When `deck-mode.txt` says `editable`, skip Phases R/D/I below and follow this loop instead (contract details and full example: `references/editable-slide-spec.md`):

1. **Generate only text-free assets** (photos, illustration panels — no rendered text) with PaperBanana; record each asset's SHA-256. 2. **Author `slide-deck/{topic-slug}/slide-spec.json`** — native `text`, `shape`, `line`, `table`, `chart`, `image`, and `group` elements on the 13.333×7.5 in canvas, with `[Sources]` speaker notes per slide. 3. **Validate + build** (fail-closed; a missing or invalid spec is an error, never a silent image-mode fallback):

```bash bun "${SKILL_DIR}/scripts/build-deck.ts" --mode editable "slide-deck/{topic-slug}" ```

4. **Render PPTX previews** with LibreOffice + Poppler (`soffice --headless --convert-to pdf`, then `pdftoppm -png -r 150 … slide` → `slide-NN.png`). 5. **Run Critic on the previews** (preview-only; never edits the PPTX):

```bash python3 "${SKILL_DIR}/scripts/editable/review-editable.py" \ --spec "slide-deck/{topic-slug}/slide-spec.json" \ --rendered-dir "slide-deck/{topic-slug}/rendered" \ --output "slide-deck/{topic-slug}/critic-review.json" ```

6. **Map findings to element IDs** (suggestions arrive as `slide-id/element-id: …`), revise `slide-spec.json`, and rebuild. Repeat until clean.

## Phase R: Research (New Mode Only)

Skip this phase entirely in Modify mode.

**R1: Discover style libraries** — Scan all four sources and merge into a unified list.

```bash # Source 0 (PRIMARY): Local extended library (123 styles from Fooocus/ComfyUI, structured) LOCAL_STYLES="$(find ~/.claude/skills .claude/skills -maxdepth 1 -name 'paperbanana-slide-deck' -type d 2>/dev/null | head -1)/references/styles"

# Source 1: baoyu-slide-deck styles (16 slide-optimized) BAOYU_SLIDE=$(ls -td ~/.claude/plugins/cache/baoyu-skills/content-skills/*/skills/baoyu-slide-deck/references/styles 2>/dev/null | head -1)

# Source 2: baoyu-infographic styles (20 visual-rich) BAOYU_INFOG=$(ls -td ~/.claude/plugins/cache/baoyu-skills/content-skills/*/skills/baoyu-infographic/references/styles 2>/dev/null | head -1)

# Source 3: theme-factory themes (10 color/typography presets) THEME_FACTORY=$(ls -td ~/.claude/plugins/cache/anthropic-agent-skills/document-skills/*/skills/theme-factory/themes 2>/dev/null | head -1) ```

Merge: Glob all four directories for `*.md`, deduplicate by filename (priority: baoyu-slide-deck > local > baoyu-infographic > theme-factory). Present the full unified list to user during R3.

If none found: Use PaperBanana's 23 built-in presets.

**R2: Analyze content** — Topic, audience, tone, recommended slide count.

**R3: Style recommendation** — Recommend 2-3 styles based on content signals. See `references/style-guide.md` for the full style-to-content mapping table.

**R4: Interactive selection** — Use AskUserQuestion for style, audience, and slide count.

**R5: Save analysis** — Create `slide-deck/{topic-slug}/analysis.md`.

## Phase D: Design (New Mode Only)

In Modify mode, the user handles prompt edits directly.

**D1: Load style spec** — Read from baoyu styles or PaperBanana built-ins.

**D2: Generate outline** — Create `outline.md` with slide structure. See `references/outline-format.md`.

**D3: Optional outline review** — Ask user if they want to review before proceeding.

**D4: Generate prompts** — For each slide, create `prompts/NN-slide-{slug}.md`. Each prompt file has the style instructions block, then `---`, then the slide-specific content and design requirements.

## Phase I: Implement (Both Modes)

### Step I1: Image Generation (Dual Path)

**Path A — PaperBanana CLI (preferred, has critic quality review):**

```bash cd <project_root> python -m paperbanana.cli slide-batch \ --prompts-dir "slide-deck/{topic-slug}/prompts" \ --output-dir "slide-deck/{topic-slug}" \ --resolution 4k \ --iterations 2 ```

**Auto-degrade trigger:** Switch to Path B if **any** slide (not just the first) hits one of these. Don't keep retrying Path A: - `RetryError` / `ResourceExhausted` / HTTP 429 (rate-limited) - `ServerError` (5xx) or non-429 `ClientError` (4xx) - Critic takes longer than 3 minutes on any single slide - User reports "一直 429" / persistent rate limits → degrade immediately, skip further Path A retries

**Distinguish two 429 sources**:

| Source | Symptom | Response | |--------|---------|----------| | Critic 429 (VLM rate limit) | Error inside critic loop, Path A specific | Auto-degrade to Path B (no critic → bypasses the issue) | | Image-gen 429 (`gemini-3-pro-image-preview`) | Same error in Path B | Exponential backoff: `time.sleep(30 * 2**retry)` up to 5 min, then surface to user |

**Partial-batch recovery**: If some slides were already generated before 429 hit, preserve existing PNGs and resume from the next missing slide (cross-reference `prompts/*.md` with existing `NN-slide-*.png`).

> **Note (upstream sync pending):** Upstream `paperbanana` CLI (≥ #129) has native `batch_checkpoint.json` for Path A `slide-batch` — resume is automatic there. The skip logic above is for the Path B fallback code, which doesn't yet use the upstream checkpoint format.

**Path B — Direct Gemini API (fallback, no critic, stable):**

```python from google import genai from google.genai import types from PIL import Image from io import BytesIO import base64, os, time

# Read API key from paperbanana/.env client = genai.Client(api_key=GOOGLE_API_KEY)

config = types.GenerateContentConfig( response_modalities=['IMAGE'], image_config=types.ImageConfig( aspect_ratio='16:9', image_size='4K', ), )

MAX_RETRIES = 5 # after which surface to user BASE_SLEEP = 30 # seconds

for prompt_file in sorted(os.listdir(prompts_dir)): name = prompt_file.replace('.md', '') out_path = os.path.join(output_dir, f'{name}.png')

# Partial-batch resume: skip slides already generated if os.path.exists(out_path): continue

with open(os.path.join(prompts_dir, prompt_file), 'r', encoding='utf-8') as f: prompt_text = f.read()

# Exponential backoff on 429 / transient errors for retry in range(MAX_RETRIES): try: response = client.models.generate_content( model='gemini-3-pro-image-preview', contents=prompt_text, config=config, ) break except Exception as e: msg = str(e).lower() if '429' in msg or 'resource' in msg or 'rate' in msg: wait = min(BASE_SLEEP * (2 ** retry), 300) # cap at 5 min time.sleep(wait) continue raise # non-429 error → surface immediately else: raise RuntimeError(f'{name}: 429 after {MAX_RETRIES} retries, surface to user')

for part in response.candidates[0].content.parts: inline = getattr(part, 'inline_data', None) if inline and getattr(inline, 'data', None): data = inline.data img_bytes = base64.b64decode(data) if isinstance(data, str) else data img = Image.open(BytesIO(img_bytes)) img.save(out_path, 'PNG') break

time.sleep(BASE_SLEEP) # baseline cooldown between slides ```

The API key is in `<project_root>/paperbanana/.env` as `GOOGLE_API_KEY`. Read it with dotenv or manually.

### Step I2: Smart Cleanup (Pre-Merge)

**Run AFTER I1 generation, not before.** I1 is partial-batch-aware and skips already-generated slides; Cleanup's job is only to remove PNGs whose prompt was deleted/renamed since the last run. Running Cleanup before I1 would delete valid WIP slides from a resumed batch.

Sequencing: `I1 (generate + resume) → I2 (cleanup orphans) → I3 (merge)`.

1. Scan `prompts/*.md` → build expected PNG set (e.g. `01-slide-hook.md` → `01-slide-hook.png`) 2. Scan target directory for `*.png` files matching pattern `NN-slide-*.png` 3. Delete slide PNGs NOT in expected set (orphans from renamed/deleted prompts) 4. Preserve non-slide PNGs (e.g. `logo.png`, `background.png`) and all expected-set PNGs

### Step I3: Merge to PPTX

```bash # Locate skill directory dynamically (works on any platform) SKILL_DIR="$(find ~/.claude/skills .claude/skills -maxdepth 1 -name 'paperbanana-slide-deck' -type d 2>/dev/null | head -1)" bun "${SKILL_DIR}/scripts/merge-to-pptx.ts" "slide-deck/{topic-slug}" ```

If merge script unavailable: inform user that PNG images are ready but PPTX merge requires bun and the local merge-to-pptx.ts script.

## Phase V: Verify (Both Modes)

**V1: Display results** — Read and display each generated slide image. Report total slides, output directory, PPTX file path.

**V2: User feedback** — Ask: - "Looks great, done!" - "Regenerate — I'll tell you what to fix in the prompts"

**V3: Regeneration** — If user wants changes: 1. User edits the specific prompt files 2. Regenerate ALL slides (not just changed ones — ensures visual consistency) 3. Smart cleanup + re-merge PPTX 4. Return to V1

## Fallback Behavior

| Situation | Fallback | |-----------|----------| |