git:20260426.38d9c84 to git:20260807.ccc994f

- description: Narrative-first slide deck creation. Guides users through structured narrative design (ABCDEFG model), then delegates visual generation to baoyu-slide-deck. Triggers on "create slides", "make a presentation", "generate deck", "slide deck", "PPT", or when user needs to turn content into visual slides.

- context: fork

- agent: general-purpose

- ---

-

- # Slides Creator

-

- **Narrative-first slide deck creation.**

-

- This skill does what machines can't do — narrative co-design with humans — and delegates everything else to the best tool for the job (`baoyu-slide-deck`).

-

- ## First Law: The User's Voice Is Primary

-

- **This is the highest-priority rule. Nothing overrides it.**

-

- > AI cannot write high-quality content for the user. It can only help the user express their own content better.

- >

- > **Step 1 is ALWAYS: collect the user's original words.** Their transcripts, their articles, their notes, their voice. AI-generated content without user source material is garbage — polished, plausible, unusable garbage.

- >

- > **Weight hierarchy**: User's own words > User-approved external material > AI synthesis > AI invention.

- >

- > The output must sound like the user, at their best. Something they could actually say, confidently, in their own voice.

-

- **Corollary**: If the user has no existing content, your job is to help them articulate their thoughts through structured conversation — NOT to fabricate content for them.

-

- **Corollary**: External materials (articles, references) must be presented to the user for selection and validation. AI does not decide what is relevant. The user does.

-

- **See**: `references/content-creation-first-law.md` for full principle, application to all content types, and failure modes.

-

- ## Architecture

-

- ```

- slides-creator (this skill)

- ├── Phase 0: Source Collection ← Gather user's original words

- ├── Phase 1: Narrative Design ← Human expertise + ABCDEFG discussion

- ├── Phase 2: Content Structuring ← Convert narrative to machine-readable input

- ├── Phase 3: Delegate to baoyu-slide-deck

- │ ├── --prompts-only → outline + prompts

- │ └── --images-only → images + PPTX + PDF

- └── Phase 6: Post-processing ← Directory reorg + speaker notes extraction

- ```

-

- **Rule**: If `baoyu-slide-deck` can do it, we call it. We only do what baoyu-slide-deck cannot: narrative discussion, ABCDEFG methodology, and user's preferred directory structure.

-

- ---

-

- ## Phase 0: Source Material Collection

-

- **CRITICAL**: Do NOT proceed to Phase 1 until user source materials are collected.

-

- **Goal**: Gather the user's own words and their approved external references.

-

- ### Step 0.1: Request User's Original Content

-

- Ask the user for:

- - **Transcripts** of their past talks, meetings, or discussions

- - **Articles** they have written or approved

- - **Notes** or drafts they have prepared

- - **Previous decks** they have delivered

- - **Voice memos** or any recorded thoughts

-

- If none exist, proceed to Phase 1 with the understanding that the entire narrative must be extracted from the user's head through structured conversation.

-

- ### Step 0.2: Gather External References (Optional)

-

- - Search for relevant external materials (articles, reports, references)

- - **Present findings to the user for selection** — do not assume relevance

- - Only include materials the user explicitly approves

-

- ### Step 0.3: Organize Source Materials

-

- Save all source materials to `00-上游/`（根目录或 `source-materials/` 子目录均可）：

- ```

- 00-上游/

- ├── prompt-最初提示词.txt # 用户原始 prompt（如有）

- ├── narrative-brief.md # Phase 1 输出

- ├── content.md # Phase 2 输出（baoyu 输入）

- ├── style-instructions.md # 视觉设计 SSOT

- ├── outline.md # 来自 baoyu-slide-deck

- ├── source-materials/ # （可选子目录）

- │ ├── user-transcript-1.md

- │ ├── user-article-2.md

- │ ├── user-notes-3.md

- │ └── external-ref-4.md (user-approved)

- ```

-

- **Note**: 对于已有项目，源文件可直接放在 `00-上游/` 根目录；新建议项目时可用 `source-materials/` 子目录保持整洁。

-

- **Self-check**: Do we have the user's own words? If not, are we prepared to extract everything through conversation? Do NOT invent content.

-

- ---

-

- ## Phase 1: Narrative Structure Discussion

-

- **CRITICAL**: Do NOT generate any files in this phase. Only discuss.

-

- **Goal**: Align on the narrative arc, emotional journey, and slide-level logic before any visual work begins.

-

- **Principle**: "你不要直接去写，你应该跟我讨论"

-

- **Input**: Phase 0 source materials. Every insight in this discussion must be grounded in the user's own words or their explicitly approved references.

-

- ### Discussion Framework (ABCDEFG Model)

-

- | Step | Question | Purpose |

- |------|----------|---------|

- | A | **Attention** | How do we hook in the first 30 seconds? |

- | B | **Benefit** | What's the promised takeaway? |

- | C | **Credibility** | Why should the audience trust us? |

- | D | **Difference** | What's the contrarian or novel angle? |

- | E | **Evidence** | What proof, demo, or story backs this? |

- | F | **Framework** | What mental model do we leave them with? |

- | G | **Go** | What should they do Monday morning? |

-

- ### Required Inputs

-

- Ask user if missing:

- - **Topic**: What's the talk about? (1 sentence)

- - **Audience**: Who's listening? (technical level, role, context)

- - **Duration**: How long is the talk?

- - **Key messages**: What must they remember? (3 max)

- - **Tone**: Educational? Persuasive? Provocative? Inspirational?

- - **Existing content**: Articles, transcripts, notes, previous decks?

- - **Constraints**: Must-use content? Avoid topics? Brand guidelines?

-

- ### Discussion Checklist

-

- 1. **Opening strategy**: Shock? Story? Question? Demo?

- 2. **The arc**: Where's the tension? Where's the release?

- 3. **Transition logic**: How does each slide lead to the next?

- 4. **The "one thing"**: If they forget everything, what's the ONE thing?

- 5. **Call to action**: What do they do after the talk?

-

- ### Anti-patterns to Flag

-

- - ❌ Too many slides for the time (crowded, rushed)

- - ❌ Jumping into details without setting context

- - ❌ No emotional arc (flat, forgettable)

- - ❌ Ending without a clear takeaway

- - ❌ Trying to teach too many things at once

-

- ### Validation

-

- Summarize agreed narrative arc in 3-5 bullet points. Get explicit user confirmation before proceeding to Phase 2.

-

- **Self-check**: Did we discuss? Or did we jump to generation? If the latter, go back.

-

- ---

-

- ## Phase 2: Content Structuring

-

- **Goal**: Produce two SSOT files that baoyu-slide-deck can consume.

-

- ### 2.1 Create `narrative-brief.md`

-

- Store in `00-上游/`:

-

- ```markdown

- # Narrative Brief

-

- **Topic**: [Topic name]

- **Audience**: [description]

- **Duration**: [N min]

- **Language**: [zh/en/etc]

- **Tone**: [educational/persuasive/provocative/inspirational]

- **Key Messages**: (3 max)

- 1. ...

- 2. ...

- 3. ...

-

- ## ABCDEFG Arc

-

- | Step | Answer |

- |------|--------|

- | A - Attention | ... |

- | B - Benefit | ... |

- | C - Credibility | ... |

- | D - Difference | ... |

- | E - Evidence | ... |

- | F - Framework | ... |

- | G - Go | ... |

-

- ## Slide Count Recommendation

-

- | Duration | Recommended | Max |

- |----------|-------------|-----|

- | 10-15 min | 8-12 | 12 |

- | 20-30 min | 12-18 | 20 |

- | 30-45 min | 15-25 | 28 |

- | 45-60 min | 20-30 | 35 |

-

- **Recommended**: [N] slides for [duration] talk

-

- ## Content Sources

-

- - [ ] Original user prompt saved

- - [ ] Existing articles/notes/transcripts

- - [ ] Previous decks

-

- ## Style Direction

-

- [User's style preference or "to be decided in Phase 3"]

- ```

-

- ### 2.2 Create `content.md` (for baoyu-slide-deck)

-

- Convert narrative brief into baoyu-slide-deck input format:

-

- ```markdown

- # [Title]

-

- ## Overview

-

- [2-3 paragraph summary of the talk content]

-

- ## Key Points

-

- 1. [Point 1]

- 2. [Point 2]

- 3. [Point 3]

-

- ## Structure

-

- ### Opening ([duration])

- [Hook content]

-

- ### Section 1: [Name] ([duration])

- [Content]

-

- ### Section 2: [Name] ([duration])

- [Content]

-

- ### Closing ([duration])

- [CTA content]

-

- ## Audience

- [Same as narrative-brief]

-

- ## Notes

- [Any constraints or special requirements]

- ```

-

- ### 2.3 Create `style-instructions.md` (Optional)

-

- If user has strong style preferences, create this SSOT file in `00-上游/`:

-

- ```markdown

- <STYLE_INSTRUCTIONS>

- Design Aesthetic: [Description]

-

- Background:

- Texture: [clean/grid/organic/etc]

- Base Color: [#HEX]

-

- Typography:

- Headlines: [Style, size, color, weight]

- Body: [Style, size, color, weight]

-

- Color Palette:

- Primary Text: [#HEX] - usage

- Body Text: [#HEX] - usage

- Background: [#HEX]

- Accent 1: [#HEX] - usage

- Accent 2: [#HEX] - usage

- Accent 3: [#HEX] - usage

-

- Visual Elements:

- - [Element 1]

- - [Element 2]

-

- Density Guidelines:

- - Max [N] text elements per slide

- - [Other rules]

-

- Style Rules:

- Do: [List]

- Don't: [List]

- </STYLE_INSTRUCTIONS>

- ```

-

- **Self-check**: Read narrative-brief.md back to user. Confirm it matches the Phase 1 discussion before proceeding.

-

- **Content Integrity Check**: Every claim, quote, and example in `content.md` must be traceable to:

- 1. User's own words (from Phase 0 source materials)

- 2. User-approved external references

- 3. User's explicit statements during Phase 1 discussion

-

- AI must NOT invent facts, quotes, or examples. If the user said it, use it. If they didn't, ask them. If they don't have it, mark it as `[TODO: user to provide]`.

-

- ---

-

- ## Phase 3: Delegate to baoyu-slide-deck (Prompts)

-

- **Goal**: Generate outline and prompts using baoyu-slide-deck.

-

- ### Step 3.1: Prepare Input

-

- Ensure `content.md` is ready. If `style-instructions.md` exists, note the style preference for passing to baoyu-slide-deck.

-

- ### Step 3.2: Call baoyu-slide-deck

-

- 在 Claude Code 中调用 baoyu-slide-deck skill（两种等效方式）：

-

- ```

- /baoyu-slide-deck 00-上游/content.md --prompts-only [--style <preset>]

- ```

-

- 或直接使用 Skill 工具（当 `/` 命令不可用时）：

- ```

- Skill({"skill": "baoyu-slide-deck", "args": "00-上游/content.md --prompts-only [--style <preset>]"})

- ```

-

- **Pre-call setup**:

- 1. **Inject narrative-brief**: Append `narrative-brief.md` (or its ABCDEFG arc section) to the top of `content.md` so baoyu receives the narrative structure, not just raw content.

- 2. **Inject confirmed choices**: Prepend a metadata block to `content.md` with the already-confirmed choices. This acts as a strong signal for baoyu's auto-detect and reduces the chance of style drift during confirmation:

- ```markdown

- <!-- CONFIRMED CHOICES — do not override without discussion -->

- - Style: [preset name or custom]

- - Audience: [audience from Phase 1]

- - Slide count: [N slides for X-min talk]

- - Language: [zh/en/etc]

- - Review preference: [skip outline / skip prompts / none]

- ```

- 3. **Style selection**: If user specified a baoyu preset → use it; if custom `style-instructions.md` exists → use `--style custom`; otherwise auto-detect.

-

- **⚠️ Confirmation overlap warning**: baoyu-slide-deck Step 2 will ask the user to confirm style, audience, slide count, outline review, and prompt review. Since these were already discussed in Phase 1, **instruct the user to stick with the choices we just made** rather than reconsidering. This prevents confirmation fatigue and style drift.

-

- | User's Description | baoyu Preset |

- |-------------------|--------------|

- | Flat cartoon, tech explainer | `vector-illustration` or `bold-editorial` |

- | Hand-drawn edu, infographic, process | `hand-drawn-edu` |

- | Chalkboard, workshop | `chalkboard` or `sketch-notes` |

- | Corporate, B2B, investor deck | `corporate` or `minimal` |

- | Editorial, magazine, product launch | `bold-editorial` |

- | Journalism, explainer, science communication | `editorial-infographic` |

- | Dark, gaming, atmospheric | `dark-atmospheric` |

- | Retro, pixel, developer talk | `pixel-art` |

- | Watercolor, lifestyle, travel | `watercolor` |

- | Blueprint, technical, architecture | `blueprint` |

- | Academic, research, bilingual | `intuition-machine` |

- | Notion, SaaS, product demo | `notion` |

- | Story, fantasy, animation | `fantasy-animation` |

- | Biology, chemistry, medical | `scientific` |

- | History, heritage, vintage | `vintage` |

-

- ### Step 3.3: Post-process Prompts

-

- After baoyu-slide-deck generates prompts in `prompts/`:

-

- 1. **Copy to user's structure**: Move/copy prompts to `03-prompts/`

- 2. **Inject custom style**: If `style-instructions.md` exists, ensure FULL content is embedded in every prompt file

- 3. **Add narrative goal**: Append `// NARRATIVE GOAL` section to each prompt based on `narrative-brief.md`

-

- Prompt template addition:

- ```markdown

- ---

-

- ## NARRATIVE CONTEXT

-

- // NARRATIVE GOAL

- [What this slide achieves in the talk arc]

-

- // SPEAKER NOTES

- [What the speaker says while this slide is shown]

- ```

-

- **Self-check**: All prompts include full style-instructions.md? Narrative goals added? Files in `03-prompts/`?

-

- ---

-

- ## Phase 4: Prompt Review (Conditional)

-

- **Goal**: Human review before image generation.

-

- **If user wants to review** (recommended):

- 1. Display prompt summary table

- 2. Ask user: "Ready to generate images?"

- 3. If edits needed → user edits `03-prompts/*.md` → regenerate specific prompts via baoyu-slide-deck

-

- **If user skips review**: Proceed to Phase 5.

-

- ---

-

- ## Phase 5: Delegate to baoyu-slide-deck (Images)

-

- **Goal**: Generate slide images.

-

- ### Step 5.1: Call baoyu-slide-deck

-

- ```

- /baoyu-slide-deck . --images-only

- ```

-

- Or using Skill tool:

- ```

- Skill({"skill": "baoyu-slide-deck", "args": ". --images-only"})

- ```

-

- **Important**: baoyu-slide-deck expects prompts in a flat `prompts/` directory (its native output structure). If you have already reorganized to `03-prompts/` (Phase 6), create a temporary copy before calling:

- ```bash

- # From the project root (where 03-prompts/ exists)

- cp -r 03-prompts prompts

- /baoyu-slide-deck . --images-only

- rm -rf prompts # clean up after

- ```

-

- **Note on deliverables**: baoyu-slide-deck internally generates `.pptx` and `.pdf` via its own `merge-to-pptx.ts` and `merge-to-pdf.ts` scripts (Step 8 of its workflow). These are the **primary** deliverables — they live in baoyu's flat output directory (`slide-deck/{topic-slug}/`).

-

- The `scripts/merge_to_pptx.py` and `scripts/merge_to_pdf.py` in slides-creator are **not** duplicates. They serve a different purpose:

- - **baoyu merge**: for baoyu's flat directory structure (PNG + prompts at same level)

- - **slides-creator merge**: for the reorganized directory structure (`02-slides/` + `03-prompts/`)

-

- Use slides-creator's merge scripts only after Phase 6 reorganization, or if baoyu's merge step fails.

-

- ### Step 5.2: Visual Verification

-

- After generation:

- 1. **Test slide**: Read `01-slide-cover.png` (or first generated slide)

- 2. **Style check**: Compare against `style-instructions.md`

- 3. **Text check**: Verify Chinese/English text legibility

- 4. **If issues**: Update affected `03-prompts/*.md` → copy `cp -r 03-prompts prompts` → regenerate via `/baoyu-slide-deck . --regenerate N` (或 `Skill({"skill": "baoyu-slide-deck", "args": ". --regenerate N"})`) → clean up `rm -rf prompts`

-

- **Self-check**: All slides generated? Style consistent? Text legible?

-

- ---

-

- ## Phase 6: Post-processing & Delivery

-

- **Goal**: Reorganize baoyu-slide-deck output into user's preferred structure.

-

- ### 6.1 Directory Reorganization

-

- baoyu-slide-deck outputs to `slide-deck/{topic-slug}/`:

- ```

- slide-deck/{topic-slug}/

- ├── source-{slug}.md

- ├── outline.md

- ├── prompts/

- ├── *.png

- ├── {topic-slug}.pptx

- └── {topic-slug}.pdf

- ```

-

- Reorganize to user's structure:

- ```

- {project-name}/

- ├── 00-上游/ # Source materials

- │ ├── prompt-最初提示词.txt # Original user prompt (if saved)

- │ ├── narrative-brief.md # Phase 1 output

- │ ├── content.md # Phase 2 output (baoyu input)

- │ ├── style-instructions.md # Visual design SSOT

- │ └── outline.md # From baoyu-slide-deck

- ├── 01-成品/ # Final deliverables

- │ ├── {project-name}.pdf

- │ └── {project-name}.pptx

- ├── 02-slides/ # Generated PNGs (当前版本)

- │ ├── 01-slide-cover.png

- │ └── ...

- ├── 03-prompts/ # Per-slide prompts (SSOT)

- │ ├── v6/ # 支持版本子目录（如 v6, v7...）

- │ │ ├── 01-slide-cover.md

- │ │ └── ...

- │ └── 01-slide-cover.md # 或平铺结构

- ├── speaker-notes.md # Auto-extracted from 03-prompts/ via extract_notes.py

- ├── v6/ # baoyu-slide-deck 临时输出（需搬迁到 02-slides/）

- │ └── ...

- └── _archive/ # Historical versions

- └── v1/

- ```

-

- **Note on versioning**:

- - `03-prompts/` 支持平铺或版本子目录（`v6/`, `v7/`）。当同一项目多次迭代时，用子目录保留历史版本。

- - baoyu-slide-deck 可能直接输出到项目根目录的临时文件夹（如 `v6/`）。Post-processing 时需将这些 PNG 移动到 `02-slides/`。

-

- **Archive current version** (before major iteration):

- ```bash

- uv run scripts/archive_version.py --project /path/to/project

- ```

- Archives `02-slides/` + `03-prompts/` to `_archive/v{N}/` (auto-incremented).

-

- ### 6.2 Extract Speaker Notes

-

- Use `scripts/extract_notes.py` to extract structured notes from `03-prompts/*.md`:

-

- ```bash

- uv run scripts/extract_notes.py --prompts 03-prompts --output speaker-notes.md

- ```

-

- Extracts:

- - `// NARRATIVE GOAL` sections

- - `// SPEAKER NOTES` sections

- - Falls back to `// KEY CONTENT` if neither found

-

- Output format (`speaker-notes.md`):

- ```markdown

- # Speaker Notes

-

- ## 01-slide-cover

- **Narrative Goal**: ...

- **Speaker Notes**: ...

-

- ## 02-slide-intro

- ...

- ```

-

- **Note**: `main.ts` auto-runs this step if `03-prompts/` exists.

-

- ### 6.3 Archive Original Prompt

-

- If user provided an original prompt (like the 35KB prompt for 龙虾 vs Claude Code):

- - Save as `00-上游/prompt-最初提示词.txt`

-

- ### 6.4 Final Verification Checklist

-

- - [ ] PDF opens and all slides render correctly

- - [ ] PPTX opens without errors

- - [ ] PNG sequence numbered correctly (01, 02, ...)

- - [ ] Speaker notes cover all slides

- - [ ] Style consistent across all slides

- - [ ] No garbled or missing text

- - [ ] `00-上游/` contains all source SSOT files

- - [ ] `03-prompts/` contains all prompt files

-

- ---

-

- ## Iteration Workflow

-

- ### Path A: Content Changes

- ```

- User feedback → Update narrative-brief.md → Update content.md

- → Regenerate prompts (/baoyu-slide-deck content.md --prompts-only)

- → Regenerate images (/baoyu-slide-deck . --images-only)

- → Reorganize + extract notes

- ```

-

- ### Path B: Style Changes

- ```

- User feedback → Update style-instructions.md

- → Update all prompts (inject new style into 03-prompts/*.md)

- → Regenerate all images (via /baoyu-slide-deck . --images-only)

- → Reorganize + extract notes

- ```

-

- ### Path C: Single Slide Fix

- ```

- User feedback → Update 03-prompts/NN-slide-xxx.md

- → Copy prompts: cp -r 03-prompts prompts

- → /baoyu-slide-deck . --regenerate N

- → Clean up: rm -rf prompts

- → Replace in 02-slides/

- → Regenerate PPTX/PDF

- ```

-

- **Note on `--regenerate`**: baoyu-slide-deck reads from flat `prompts/` directory. After reorganization to `03-prompts/`, create a temporary copy (`cp -r 03-prompts prompts`) before regenerating. If you haven't reorganized yet (still in baoyu's flat structure), call directly without copying.

-

- ## Script Reference

- | Script | Purpose |

- |--------|---------|

- | `scripts/main.ts` | Post-processing: validate + extract notes + generate PDF/PPTX |

- | `scripts/merge_to_pptx.py` | Merge PNGs to PPTX with structured speaker notes from `03-prompts/*.md` |

- | `scripts/merge_to_pdf.py` | Merge PNGs to PDF (reorganized `02-slides/` structure) |

- | `scripts/validate_slides.py` | Check aspect ratio, naming, missing slides |

- | `scripts/extract_notes.py` | Extract structured speaker notes from `03-prompts/*.md` to `speaker-notes.md` |

- | `scripts/archive_version.py` | Archive `02-slides/` + `03-prompts/` to `_archive/v{N}/` |

- ---

- ## Failure Log (Do NOT Repeat)

- | Failure | Root Cause | Prevention |

- |---------|-----------|------------|

- | **AI wrote content for the user — polished garbage** | Violated First Law: skipped Phase 0, fabricated quotes/examples. See `references/content-creation-first-law.md` | **First Law is absolute**: collect user's words FIRST. No source material = STOP and ask. AI assists expression, never replaces it |

- | Generated 30 slides for 20-min talk | Didn't enforce slide count guide | Check duration ÷ 2 = max slides |

- | Style drift between versions | Style instructions not in prompts | Paste FULL style-instructions.md into every prompt |

- | Text unreadable in images | Model doesn't support Chinese well | Test with Chinese text first |

- | Narrative arc flat | Jumped to prompts without Phase 1 | ALWAYS discuss narrative first |

- | User unhappy with first draft | Didn't confirm before batch | Generate ONE test slide, get approval |

- | Directory mess | Didn't use consistent structure | Always use 00-上游/01-成品/02-slides/03-prompts |

- | Redundant work | Tried to replace baoyu-slide-deck | Delegate visual generation, focus on narrative |

- | Merge scripts questioned as duplicates | Baoyu merge scripts exist but: (1) path unstable (`~/.claude/plugins/...`); (2) expect flat `prompts/` dir; (3) inject full base prompt as notes noise | Keep own merge scripts for reorganized structure. Validate before deleting — call baoyu merge first if accessible |

- ---

- ## References

- - `references/content-creation-first-law.md` — Universal principle: user's voice is primary, applies to all content types (slides, articles, ads, courses)

- - `references/narrative-design-guide.md` — ABCDEFG model detailed guide

- - `references/prompt-templates/` — Prompt templates for common slide types

- - `references/style-gallery.md` — Visual style gallery with examples