Turn an article or voiceover script, step by step, into a screen-recordable "webpage disguised as a video", with optional synthesized voiceover audio. Deliverable = Vite + React + TS project + audio split by chapter.
Applicable scenarios
- "I have a voiceover script / an article, help me turn it into a video" — voiceover-driven content
- Want to make a "dynamic PPT"
- 16:9 landscape screen recording, large text, whitespace, every screen must have motion effects
- Teaching / product demos / keynotes that want a cinematic feel
- Bilibili / YouTube / Douyin video content
This Skill is centered on methodology + collaboration flow. The scaffold template provides tokens and primitives, but every aesthetic decision (color scheme, typography, motion character) should be redesigned for your theme — don't copy it wholesale.
Workflow overview
Phase 1 内容编写
1.1 识别用户输入
1.2 一次产出 script.md + outline.md
（口播稿 + 开发计划）
▼
[Checkpoint Plan] ← 必须停。一次对齐 5 件事：
稿子 / outline / 主题 / 素材 / 开发模式
▼
Phase 2 网页开发
2.1 脚手架（按选定主题）
2.2 第 1 章 = 主线程 + 完整版本（强制 anchor）
▼
[硬节点] 用户验收第 1 章 ← 不可跳过
▼
2.3 第 2~N 章（按选定模式：A 逐章 / B 顺序 / C 并行）
▼
[Checkpoint Audio] ← 必须停。是否合成音频
▼
Phase 3 音频合成（可选）
▼
Phase 4 录屏 + 后期
Working directory conventions (agent creates / edits under the user's current directory):
my-video/
├── article.md # 用户给原文时必有 —— 不删！开发阶段画面信息源
├── script.md # 必有：保持原文语言的平台化口播稿（决定节拍）
├── outline.md # 必有：开发计划（章节切分 + 每步内容 + 信息池）
└── presentation/ # 脚手架产出的 Vite + React + TS 项目
├── src/chapters/<NN>-<id>/
│ ├── <Chapter>.tsx # 视觉实现
│ ├── <Chapter>.css
│ └── narrations.ts # ★ step 数 + 口播文本的唯一真相源
├── scripts/
│ ├── extract-narrations.ts # 扫所有 narrations.ts → audio-segments.json
│ ├── synthesize-audio.sh # provider-agnostic runner（循环 segments）
│ └── tts-providers/ # 每 provider 一个 .sh（内置 2 个）
│ ├── README.md # 三函数契约 + 5 段现成代码片段（11labs / edge-tts / say / azure / gcloud）
│ ├── minimax.sh # 默认 provider，用 mmx-cli
│ └── openai.sh # 内置 OpenAI TTS（curl + OPENAI_API_KEY）
├── audio-segments.json # extract 产出（合成前 review）
└── public/audio/<id>/<N>.mp3 # 可选：合成的音频
The key：
narrations.tsis the step count and audio synthesis'ssingle source of truth. The maximum N + 1 of.tsxappearing in chapterif (step === N)must equalnarrations.length. This guarantees that 5 places (script / outline / chapter code / chapters.ts / audio files) will never drift.
Mandatory self-check protocol (runs through the entire Skill)
For each of the three deliverables below,after completion you must run self-check → fix → then report / proceed：
| Deliverable | Source of the self-check checklist |
|---|---|
script.md |
SCRIPT-STYLE.md Three-layer self-check (form / substance / read it aloud) |
outline.md |
OUTLINE-FORMAT.md self-check |
| Single-chapter implementation complete | CHAPTER-CRAFT.md completion self-check |
Execution method(degrade by capability,prefer the more isolated approach）：
- Agent Teams (best): open an independent reviewer agent, give it "deliverable file path + corresponding checklist + key context", have it verify item by item andreport conclusions strictly (which items pass / which items fail + evidence + rewrite suggestions).
- subAgent (second best): if there is no Teams capability but a subagent can be opened, use a subagent to run the same flow.
- Self-check (fallback): if the current agent lacks all of the above capabilities, thenstrictly verify item by item by itself — visual inspection and waving it through are not allowed.
Iron rule: after getting the conclusions,first fix the deliverable according to the fail items, then report to the user "done
- self-check conclusion + what was changed".Reporting the raw conclusions directly without fixing = violation。
File reading guide for each phase
Different phases read different files.In long sessions the agent easily forgets principles, especially since Phase 2.4's "implement a single chapter" repeats N times — each time you must review the core constraints.
| Phase | Must-read (look every time) | Read once through / look up on demand |
|---|---|---|
| Phase 1.1-1.2 Content Writing | references/SCRIPT-STYLE.md + references/OUTLINE-FORMAT.md + article.md(user's original text, if any) |
—— |
| Checkpoint Plan Choose Topic | —— | themes/*/theme.json(dynamically read all, list checklist + bestFor recommendations + descriptionZh）；references/THEMES.md(when the user wants to learn about the theme system) |
| Phase 2.1 Scaffolding | —— | Read this section of SKILL.md once |
| Phase 2.4 Implement a single chapter (×N times, called by 2.2 / 2.3) | references/CHAPTER-CRAFT.md Single entry point —— Part 0 Ten Principles / Part 1 Five Questions to Start / Part 2 Relationship→Action Decision Tree / Part 3 Visual Toolbox / Part 4 Duration Reference / Part 5 Anti-AI-Flavor Anti-Patterns / Part 6 Code Hard Rules (including narrations.ts mandatory constraints) / Part 7 Completion Self-Check / Part 8 Feedback Quick Reference + the current topic's themes/<id>/theme.json + the current chapter's outline.md paragraph + article.md this chapter's corresponding paragraph + material list |
references/EXAMPLES/(structural illustration, not a template to copy);references/THEMES.md complete token contract |
| Phase 3 Audio Synthesis | references/AUDIO.md(including narrations.ts → segments.json → any provider flow, built-in minimax + openai) |
templates/scripts/tts-providers/README.md(when switching provider / bringing your own TTS) |
| Phase 4 Screen Recording + Post-Production | references/RECORDING.md(including ?auto=1 automatic screen recording) |
—— |
| Select / Create / Switch Theme | —— | references/THEMES.md |
When writing a chapter, read only one
CHAPTER-CRAFT.md. The ten principles / start self-prompting / decision tree / anti-AI-flavor anti-patterns / completion self-check are all merged into this single entry point.EXAMPLES/not required reading —— first design freely based on the content, and only consult it when stuck (consult the "form" by anchor, don't copy it directly).
Phase 1 —— Content Writing (produced in one pass)
1.1 Identify User Input
| What the user provides | What should be done |
|---|---|
| Original article (written language / WeChat public account / paper / blog) | Produce in one pass script.md + outline.md(1.2), go through Checkpoint Plan |
| Direct spoken script / video script | Save to disk as script.md, produce in one pass outline.md(simplified version of 1.2), go through Checkpoint Plan |
| Nothing at all, just saying "help me make a video about topic X" | Ask back: first provide some material or an outline. The Skill does not conceive content on the user's behalf |
1.2 Produce script.md + outline.md in one pass
Both deliverables are completed in a single act of thinking：
- Generate
script.md: according toreferences/SCRIPT-STYLE.md's rules, convert the article into a platform-adapted spoken script that preserves the original language.Keeparticle.mddo not delete——it is the detail source for the outline when writing the information pool and the chapter implementation visuals (dual-source principle). - Generate
outline.md: according toreferences/OUTLINE-FORMAT.mdrules, split chapters + split steps + extract from each chapter's first paragraph theinformation pool。
Boundaries of the outline(key):
| outline must include | outline must not include |
|---|---|
| Chapter splitting / number of steps per chapter / estimated time | Specific animation types (blur clear / wipe / spring) |
| Screen content for each step (hero / data / tagline / list item) | CSS implementation means (filter / SVG / clip-path) |
| Chapter-levelInformation pool: numbers / quotes / cases / tags extracted from article | Duration values (do not write 2.5s / 80120ms） |
| Step-level relationship name prefix (optional hint such as "contrast pairing" / "progressive list" / "punchline") | Micro-rhythms such as continuous micro-motion / staggered amounts |
The reason outline does not specify animations: hardcoding animations = chapter agent degenerates into a translation machine; leaving it blank lets the chapter agent design freely at the start of each step according to the
CHAPTER-CRAFT.md"content-driven decision tree", which is what creates a real video feel. SeeCHAPTER-CRAFT.mdPart 0 Principle 7.
After saving to disk, you must run self-check before proceeding to Checkpoint Plan: according to the "mandatory self-check protocol" above, separately
execute for script.md / outline.md (prefer Agent Teams → subAgent → self-check),
and only after fixing according to the conclusion proceed to Checkpoint Plan.
Checkpoint Plan —— align 5 things at once (hard node）
script.md + outline.md After writing, you must stop.At this single node the user confirms
5 things at the same time。
Preparatory work the agent should do at this point
- Read all
themes/*/theme.jsonto getnameZh/descriptionZh/bestFor/mood—— Do not hardcode the list - Based on
script.md's content type / keywords / tone,proactivelypick 2~3 sets from the themebest-matching recommendations(matching thebestForfield) - Scan the
outline.md"material list" section at the end
Summary template (skeleton, agent fills in as appropriate)
内容计划写完，产出文件：
📄 article.md {若用户给原文则保留}
📄 script.md {X} 字 / ~{T} 分钟
📄 outline.md {N} 章 / {M} 步 + 每章信息池 + 末尾素材清单
章节速览：
1. <id> <章节标题> <S> 步 ~<T>s
2. ...
接下来一次对齐 5 件事：
1. 稿子 (script.md) 要不要改？
可以直接编辑文件，或口头告诉我修改方向。
2. 开发计划 (outline.md) 要不要改？重点看：
- 章节切分 / step 数 / 估时是否合理（合理判断：每章 30~60s）
- 每步屏幕内容是否清晰
- 每章首段「信息池」是否有足够的 article 细节供画面挂
- 末尾素材清单是否完整
3. 选哪个主题？我的推荐：
★ <推荐 1：nameZh (id)> — 因为 <bestFor 命中>；<descriptionZh 摘要>
★ <推荐 2 / 推荐 3>
其它可选：<剩余主题，nameZh + 一句话>
也可以让我帮你做新主题（详见 references/THEMES.md）。
4. 真素材怎么准备？粗看本视频要的图：<列粗略清单>
a) 我从 <现有素材路径> 帮你挑 b) 你自己提供 c) 全部 placeholder
5. 开发模式选哪个？
**第 1 章无论哪种模式都必须主线程做完 + 用户验收**（强制 anchor）。
差异在第 2 章及之后：
A) 默认 · 逐章确认（推荐）
每章做完都暂停验收 → 风险可控 / 节奏最稳
B) 第 1 章后顺序开发（不并行）
第 2~N 章主线程顺序做完后统一验收 → 速度中 / 适合 agent 不支持并行
C) 第 1 章后并行开发（subagent）
第 2~N 章用 subagent 并行 → 最快 / 用户控并行数（一次几章）
⚠️ 风格各章会有差异（这是预期，主题禁区兜底）
After receiving feedback:
- Script / outline needs changes: edit the file directly, ping once after editing (or describe orally and let the agent change it)
- The theme must be explicitbefore entering Phase 2. If the user says "you pick the theme for me" → take your 1st recommendation, tell the user what you chose and why, giving them a chance to change their mind
- Mode selected → enter Phase 2
Phase 2 —— Web development
2.1 Scaffolding
bash <path-to-web-video-presentation>/scripts/scaffold.sh \
./presentation \
--theme=<用户选的主题 id>
bash <path-to-web-video-presentation>/scripts/scaffold.sh --list-themes
Custom theme → first follow the
references/THEMES.md"create new theme" process to make athemes/<my-theme>/, then--theme=<my-theme>。
The scaffold comes with a 01-example demo. Before writing the first chapter's real content,delete it：
rm -rf presentation/src/chapters/01-example
and in presentation/src/registry/chapters.ts remove the EXAMPLE_CHAPTER
import and array entry.
2.2 Chapter 1 —— Main thread + mandatory acceptance
Core: Chapter 1 = complete version in one go (rhythm + visuals + real materials all in place). There is no concept of a "skeleton version" —— the first chapter must be made intosomething the user can directly acceptas a sample.
Why Chapter 1 must be on the main thread:
- It is
CHAPTER-CRAFT.mdthis set of guidelines' first landing underthe current theme + current subject matter. - If the guidelines have blind spots / the theme colors / font tokens are insufficient, Chapter 1 will definitely expose it —— at this point human feedback lets you fix the guidelines / adjust the theme,and fixing early costs the least
- Subsequent chapters (whether sequential or parallel) must reference the code patterns from Chapter 1, so Chapter 1 = the "style anchor" for the current project (consistency between chapters is not required, but each individual chapter must be fully convincing on its own)
After finishing Chapter 1, you must stopand wait for user acceptance:
第 1 章 <id> 做完了，dev server 在 localhost:5173 运行。
验收重点：
□ 视觉气质对不对？符合 <theme nameZh> 的预期吗？
□ 节奏对不对？某些步太快 / 太慢 / 信息太薄？
□ 内容驱动动画是否到位？还是有几步是无脑入场动画？
□ 双源原则：屏幕画面有没有"口播没念但 article 能挂"的细节？
□ 反 AI 味检查：紫粉渐变 / 圆角彩色边框 / 假插画 / emoji 是否有？
问题告诉我，我针对性改。OK 了告诉我"继续"，我按选定模式做第 2 章及之后。
2.3 Chapters 2~N — Per the chosen mode
Common rules across all modes: each chapter is developed independently per CHAPTER-CRAFT.md
.Style is not required to be fully consistent between chapters — theme colors / font tokens provide visual fallback and
unify things; animations / pacing / visual presentation are free for each chapter to explore, as intended by design.
Mode A · Default · Chapter-by-chapter confirmation
Chapter 2 done → pause for acceptance → OK → Chapter 3 → pause → ... → Chapter N.Each chapter is accepted independently, problems can be fixed at any time,lowest risk, most stable pacing。When the user does not explicitly choose a mode, this is the default。
Mode B · Sequential development after Chapter 1
Chapter 2 → Chapter 3 → ... → Chapter N done sequentially on the main thread, with unified acceptance at the end. Medium speed, suitable for environments where the agent does not support parallel tasks.
Mode C · Parallel development after Chapter 1 (subagent)
Use subagents to complete Chapters 2~N in parallel; the maximum parallelism is controlled by the user ("4 chapters at a time" / "2 chapters at a time").Fastest, but styles will differ across chapters — this is expected, because:
- Each subagent cannot see the output of other subagents and cannot mechanically align with them
- Chapter code is physically separated (each chapter has its own folder / its own CSS prefix), so it will not break each other
- Theme tokens provide visual fallback and unity (colors / fonts / hero numbers / cards / divider character / decoration), so the overall feel will not drift
- Style inconsistency = the breathing feel of hand-made videos(multiple voices / multiple perspectives)
The prompt for parallel subagents must include:
- The current chapter's outline section (including the information pool)
references/CHAPTER-CRAFT.mdpath (single required reading — visual presentation requirements + progressive reveal + dual-source principle + anti-AI flavor + code red lines + completion self-check are all in this one file)- The current theme
theme.json'sdescriptionZh/mood/bestFor(reference feel is enough; animations / duration / font size / emoji are freely decided by the chapter agent) - Chapter 1 code as a "code style" reference(not a "visual plagiarism target")
- Hard rule: each chapter has an independent CSS prefix (
.cd-/.mg-/.pm-/ ...); do not modifychapters.ts; when done runnpx tsc --noEmit
Important: no matter which mode is chosen,the user can switch modes at any time. After Chapter 2 is OK, the user can say "do the rest in parallel" / "do the rest chapter by chapter" and either is fine.
2.4 Implement a single chapter (required for every chapter)
For detailed guidance see references/CHAPTER-CRAFT.md ——
single required reading entry, covering: visual presentation requirements / progressive reveal / content trade-offs / dual-source principle
/ basic aesthetics of video presentation / anti-AI flavor / code red lines / completion self-check.
Core points(detailed in CHAPTER-CRAFT.md):
- Each chapter must have a CSS / SVG / Canvas / JS visual demonstration, text-only chapters are forbidden
- Reveal step by step: checklists / lists must be 1 item = 1 step, showing all at once is forbidden
- Dual-source principle: pacing follows the voiceover script (order must not be scrambled), details are extracted from the original article (information pool + this chapter's article paragraphs)
- Go through the completion self-check item by item, if it doesn't meet the standard go back and fix it — execute according to the "Hard Self-Check Protocol" above (prioritize Agent Teams → subAgent → self-check),after fixing, report this chapter's delivery to the user
2.5 After major changes, bump STORAGE_KEY
Changes chapters.ts(adding / deleting / reordering chapters, or a chapter's narrations.ts
length change) after,bump presentation/src/hooks/useStepper.ts of the
STORAGE_KEY(such as v4 → v5), to avoid the persisted cursor landing on a nonexistent step.
Checkpoint Audio —— whether to synthesize audio (hard node）
After Phase 2 ends, you must stop and ask the user:
网页做完，{N} 章 {M} 步，dev server 在 localhost:5173 跑着。
要不要合成音频做"自动播放录屏"？
✓ 合成 → 扫所有章节的 narrations.ts 出 audio-segments.json，
调 TTS provider 合成每步一个 mp3 到 public/audio/。
合成完后用 ?auto=1 模式可以一镜到底录屏（音视频天然同步）。
内置两个 provider：
• minimax (mmx-cli) —— 默认，中文音色稳
• openai (OPENAI_API_KEY) —— curl-based，多数已有 key
其它后端 (ElevenLabs / edge-tts 免费 / macOS say 离线 /
Azure / Google) 见 scripts/tts-providers/README.md 的现成片段。
✗ 不合成 → 跳过 Phase 3，直接 Phase 4 用手动录屏 + 后期配音。
Synthesize → Phase 3. Don't synthesize → go directly to Phase 4.
Phase 3 —— Audio synthesis (optional)
See references/AUDIO.mdfor the detailed process. Brief version:
cd presentation
npm run extract-narrations # 扫所有 narrations.ts → audio-segments.json
# 让用户扫一眼 audio-segments.json 确认文本对
npm run synthesize-audio # 默认 minimax provider，增量
# 或用内置 openai (要 OPENAI_API_KEY):
PRESENTATION_TTS=openai npm run synthesize-audio
# 或自定义：写一个 scripts/tts-providers/<name>.sh，见该目录的 README.md
After synthesis, tell the user: output location / total segment count / which segments have abnormal durations (too long = that step should be split; too short = the copy is too thin) —— giving one last chance to calibrate the pacing. Then proceed to Phase 4.
Phase 4 —— Screen recording + post-production
See references/RECORDING.mdfor details. Two paths:
| Scenario | Recommended path |
|---|---|
| Phase 3 audio already synthesized | Auto mode one-take: open in the browser localhost:5173/?auto=1 → press SPACE → the whole film plays automatically → stop recording → trim the head and tail and it's the finished film,no post-production audio track syncing needed |
| Phase 3 skipped | Default Manual mode, manually click to advance → dub with any post-production editing tool |
After Phase 3 / Checkpoint Audio, the agentproactively tells the userthe suitable screen recording path.
Ten principles (one-sentence checklist)
See references/CHAPTER-CRAFT.md
Part 0 —— for the full expansion, look it up there when writing chapters, the following is just an index.
| # | Principle | One sentence |
|---|---|---|
| 1 | 16:9 fixed stage | Content 1920×1080 + transform scale, no responsive |
| 2 | Global step counter | Chapters are pure functions of step, no timers |
| 3 | Each step occupies the full screen | if (step === N) return <FullScene /> |
| 4 | Voiceover beat = step | One beat = one step = one focused idea |
| 5 | Hidden corner controls | Progress bar / pager default opacity 0 |
| 6 | Stage has no chrome | No header / footer / page number / brand bar |
| 7 | Content-driven animation | First look for intrinsic motion, only fall back to entrance animation if none is found; use continuous micro-motion with caution |
| 8 | Reveal multiple points one by one | 1 item = 1 step, synchronously staggering N items is forbidden |
| 9 | The whole film shares one theme | No surface color flipping between chapters;colors / fonts go through tokens, other scale chapters are free |
| 10 | Dual-source principle | script sets the pacing,article sets the visual density(lands in the information pool) |
Common user feedback quick reference
See the simplified table in references/CHAPTER-CRAFT.md
Part 8 "Common feedback quick reference".Key: first locate which layer it is (pacing / visual / content
/ code), then change the smallest slice,do not redo the entire chapter。
Related resources
Annotated by "when to read", to avoid reading everything at once:
| File | When to read | Content |
|---|---|---|
references/SCRIPT-STYLE.md |
Required for Phase 1.2 | Article → spoken script rules, platform variants |
references/OUTLINE-FORMAT.md |
Required for Phase 1.2 | outline.md field spec, naming conventions, chapter segmentation, information pool |
references/CHAPTER-CRAFT.md |
Single required entry point per chapter for Phase 2.4 | Part 0 Ten principles / Part 1 Five starting questions / Part 2 Relationship→action decision tree / Part 3 Visual toolbox / Part 4 Duration / Part 5 Anti-AI-flavor anti-patterns / Part 6 Code hard rules / Part 7 Completion self-check / Part 8 Feedback quick reference |
references/EXAMPLES/ |
Optional — look at the structure | Chapter structure examples (hook / list-reveal / case-tech-review);not a template to copy |
references/THEMES.md |
When selecting / creating / slicing topics | Complete token contract + built-in theme list + creation workflow |
references/AUDIO.md |
Read only in Phase 3 | Provider-agnostic audio synthesis workflow, built-in minimax usage, switching provider paths, troubleshooting |
templates/scripts/tts-providers/README.md |
When switching / adding a TTS provider | Three-function contract + 2 built-in (minimax / openai) + 5 ready-made code snippets (ElevenLabs / edge-tts / macOS say / Azure / Google) |
references/RECORDING.md |
Read only in Phase 4 | Screen recording tools + post-production compositing |
themes/ |
Flip through during Checkpoint Plan / Phase 1.2 | Built-in themes (each includes theme.json + tokens.css） |
scripts/scaffold.sh |
Run once in Phase 2.1 | One-click project scaffolding |