Web Video Presentation
Turns an article or voiceover script into a screen-recordable "webpage disguised as a video," step by step. Optionally synthesize voiceover audio. Output = Vite + React + TS project + chapter-split audio.
Suitable Scenarios
- "I have a voiceover script / article, help me make a video" — voiceover-driven content
- Want to create a "dynamic PPT"
- 16:9 landscape screen recording, large text, white space, every screen must have animation
- Teaching / product demos / keynotes with a cinematic feel
- Bilibili / YouTube / Douyin video content
This skill focuses on methodology + collaboration workflow. The scaffold template provides tokens and primitives, but every aesthetic decision (color scheme, font, animation style) should be redesigned for your topic — don't copy.
Workflow Overview
Phase 1 Content Writing
1.1 Identify User Input
1.2 One-shot output script.md + outline.md
(voiceover script + development plan)
▼
[Checkpoint Plan] ← Must stop. Align on 5 things at once:
Script / Outline / Theme / Assets / Dev Mode
▼
Phase 2 Web Development
2.1 Scaffold (with selected theme)
2.2 Chapter 1 = main thread + complete version (mandatory anchor)
▼
[Hard Node] User reviews Chapter 1 ← Cannot skip
▼
2.3 Chapters 2~N (with selected mode: A chapter-by-chapter / B sequential / C parallel)
▼
[Checkpoint Audio] ← Must stop. Decide whether to synthesize audio
▼
Phase 3 Audio Synthesis (optional)
▼
Phase 4 Screen Recording + Post-production
Working directory conventions (agent creates / edits in the user's current directory):
my-video/
├── article.md # Present when user provides original text — do not delete! Source of visual info during development
├── script.md # Mandatory: Platform-adapted voiceover script in the original language (determines beats)
├── outline.md # Mandatory: Development plan (chapter splits + per-step content + info pool)
└── presentation/ # Scaffolded Vite + React + TS project
├── src/chapters/<NN>-<id>/
│ ├── <Chapter>.tsx # Visual implementation
│ ├── <Chapter>.css
│ └── narrations.ts # ★ Single source of truth for step count + voiceover text
├── scripts/
│ ├── extract-narrations.ts # Scans all narrations.ts → audio-segments.json
│ ├── synthesize-audio.sh # Provider-agnostic runner (loops over segments)
│ └── tts-providers/ # One .sh per provider (2 built-in)
│ ├── README.md # Three-function contract + 5 ready-to-use code snippets (11labs / edge-tts / say / azure / gcloud)
│ ├── minimax.sh # Default provider, uses mmx-cli
│ └── openai.sh # Built-in OpenAI TTS (curl + OPENAI_API_KEY)
├── audio-segments.json # Extract output (review before synthesis)
└── public/audio/<id>/<N>.mp3 # Optional: Synthesized audio
Key:
narrations.tsis the single source of truth for step count and audio synthesis. The maximum N + 1 inif (step === N)in the chapter.tsxmust equalnarrations.length. This ensures that 5 locations (script / outline / chapter code / chapters.ts / audio files) never drift.
Mandatory Self-Check Protocol (Throughout This Skill)
For each of the three outputs below, after completion, you must self-check → fix → then report / proceed:
| Output | Self-Check Source |
|---|---|
script.md | SCRIPT-STYLE.md three-layer self-check (form / substance / read-aloud) |
outline.md | OUTLINE-FORMAT.md self-check |
| Single chapter implementation complete | CHAPTER-CRAFT.md completion self-check |
Execution Method (descending capability, prefer the most isolated approach):
- Agent Teams (best): Open a separate reviewer agent, give it "output file path + corresponding checklist + key context," ask it to check item by item and strictly report conclusions (which items pass / which fail + evidence + rewrite suggestions).
- subAgent (next best): If no Teams capability but subagent is available, use a subagent with the same process.
- Self-check (fallback): If the current agent has neither capability, strictly check each item yourself — do not just glance and pass.
Iron rule: After getting the conclusion, fix the output according to the failing items first, then report to the user "done + self-check conclusion + what was fixed." Reporting the raw conclusion without fixing = violation.
Phase-by-Phase File Reading Guide
Read different files at different phases. In long sessions, the agent may forget principles, especially Phase 2.4's "implement a single chapter" which repeats N times — core constraints must be revisited each time.
| Phase | Must Read (every time) | Read Once / Query 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 Select Theme | — | themes/*/theme.json (read all dynamically, list + bestFor recommendation + description); references/THEMES.md (when user wants to understand the theme system) |
| Phase 2.1 Scaffold | — | SKILL.md this section once |
| Phase 2.4 Implement Single Chapter (×N times, called by 2.2 / 2.3) | references/CHAPTER-CRAFT.md single entry — Part 0 Ten Principles / Part 1 Start-up 5 Questions / Part 2 Relationship→Action Decision Tree / Part 3 Visual Toolkit / Part 4 Duration Reference / Part 5 Anti-AI Anti-Patterns / Part 6 Code Hard Rules (including narrations.ts mandatory constraints) / Part 7 Completion Self-Check / Part 8 Feedback Quick Reference + current theme's themes/<id>/theme.json + current chapter's outline.md paragraph + article.md corresponding paragraph for this chapter + asset list | references/EXAMPLES/ (structural reference, not a template to copy); references/THEMES.md complete token contract |
| Phase 3 Audio Synthesis | references/AUDIO.md (includes narrations.ts → segments.json → arbitrary provider workflow, built-in minimax + openai) | templates/scripts/tts-providers/README.md (when changing providers / using custom TTS) |
| Phase 4 Screen Recording + Post-production | references/RECORDING.md (includes ?auto=1 auto-recording) | — |
| Select / Create / Customize Theme | — | references/THEMES.md |
When writing chapters, read only one
CHAPTER-CRAFT.md. Ten Principles / start-up self-prompting / Decision Tree / Anti-AI Anti-Patterns / Completion Self-Check all merged into this single entry.EXAMPLES/is not mandatory — design freely based on content first, only refer when stuck (refer to "shape," not copy).
Phase 1 — Content Writing (One-Shot Output)
1.1 Identify User Input
| What the User Provides | What to Do |
|---|---|
| Original article (written language / WeChat public account / thesis / blog) | One-shot output script.md + outline.md (1.2), go to Checkpoint Plan |
| Direct voiceover script / video script | Save as script.md, one-shot output outline.md (simplified 1.2), go to Checkpoint Plan |
| Nothing, just says "Help me make a video on topic X" | Ask back: Provide some material or an outline first. This skill does not invent content for the user |
1.2 One-Shot Output script.md + outline.md
Produce both outputs in one thinking session:
- Generate
script.md: According to the rules inreferences/SCRIPT-STYLE.md, convert the article into a platform-adapted voiceover script in the original language. Keeparticle.md— do not delete — it is the source of detail for the info pool in the outline and for visuals during chapter implementation (dual-source principle). - Generate
outline.md: According to the rules inreferences/OUTLINE-FORMAT.md, split into chapters + split into steps + extract the info pool from the first paragraph of each chapter.
Boundaries of the outline (key):
| What outline MUST write | What outline MUST NOT write |
|---|---|
| Chapter splits / steps per chapter / estimated time | Specific animation types (blur clear / wipe / spring) |
| Per-step screen content (hero / data / tagline / list items) | CSS implementation details (filter / SVG / clip-path) |
| Chapter-level info pool: numbers / quotes / cases / tags extracted from article | Duration values (don't write |
| Step-level relationship prefix ("contrast" / "progressive list" / "key quote" etc. optional hints) | Micro-rhythm like persistent micro-animations / staggered timing |
Reason outline doesn't write animations: Hardcoding animations reduces the chapter agent to a translation machine; leaving them blank allows the chapter agent to freely design at each step using the "content-driven decision tree" from
CHAPTER-CRAFT.md, achieving a true video feel. SeeCHAPTER-CRAFT.mdPart 0 Principle 7.
After saving, must self-check before proceeding to Checkpoint Plan: Execute the "Mandatory Self-Check Protocol" above for script.md / outline.md respectively (prioritize Agent Teams → subAgent → self-check), fix according to conclusions, then enter Checkpoint Plan.
Checkpoint Plan — Align on 5 Things at Once (Hard Node)
After script.md + outline.md are written, you must stop. The user confirms 5 things at this single node.
Agent's Preparation at This Point
- Read all
themes/*/theme.jsonto getname/description/bestFor/mood— do not hardcode the list - Based on the content type / keywords / tone of
script.md, proactively pick 2~3 best-matching recommendations from the themes (match thebestForfield) - Scan the "Asset List" section at the end of
outline.md
Summary Template (skeleton, agent fills as appropriate)
Content plan written, output files:
📄 article.md {if user provided original text, keep}
📄 script.md {X} characters / ~{T} minutes
📄 outline.md {N} chapters / {M} steps + per-chapter info pool + asset list at end
Chapter overview:
1. <id> <chapter title> <S> steps ~<T>s
2. ...
Next, align on 5 things at once:
1. Script (script.md) — any changes needed?
You can edit the file directly, or verbally tell me the direction.
2. Development plan (outline.md) — any changes needed? Key points:
- Are chapter splits / step counts / estimated times reasonable (reasonable = ~30~60s per chapter)
- Is per-step screen content clear
- Does the first paragraph "info pool" of each chapter have enough article details for visuals
- Is the asset list at the end complete
3. Which theme to choose? My recommendations:
★ <Recommendation 1: name (id)> — because <bestFor match>; <description summary>
★ <Recommendation 2 / 3>
Other options: <remaining themes, name + one-liner>
You can also ask me to create a new theme (see references/THEMES.md).
4. How to prepare real assets? Rough list of images needed for this video: <rough list>
a) I pick from <existing asset path> b) You provide them yourself c) All placeholders
5. Which development mode to choose?
**Chapter 1, regardless of mode, must be done on the main thread + user reviewed** (mandatory anchor).
Difference starts from Chapter 2 onwards:
A) Default · Chapter-by-chapter confirmation (recommended)
Pause and review after each chapter → risk controllable / most stable pace
B) Sequential development after Chapter 1 (not parallel)
Chapters 2~N done sequentially on the main thread, then reviewed all at once → moderate speed / good for agents that don't support parallel
C) Parallel development after Chapter 1 (subagent)
Chapters 2~N done in parallel using subagents → fastest / user controls max concurrency (how many chapters at once)
⚠️ Style may vary between chapters (expected — themes provide a safety net)
After receiving feedback:
- If script / outline needs changes: edit the files directly, ping once after editing (or verbally describe, agent edits)
- Theme must be explicitly decided before entering Phase 2. User says "You choose the theme for me" → take your first recommendation, tell the user what you chose and why, give them a chance to undo
- Mode selected → enter Phase 2
Phase 2 — Web Development
2.1 Scaffold
bash <path-to-web-video-presentation>/scripts/scaffold.sh \
./presentation \
--theme=<user's selected theme id>
bash <path-to-web-video-presentation>/scripts/scaffold.sh --list-themes
Custom theme → first follow the "Create New Theme" process in
references/THEMES.mdto create athemes/<my-theme>/, then--theme=<my-theme>.
The scaffold includes a 01-example demo. Delete it before writing real content for Chapter 1:
rm -rf presentation/src/chapters/01-example
Also remove the EXAMPLE_CHAPTER import and array entry in presentation/src/registry/chapters.ts.
2.2 Chapter 1 — Main Thread + Mandatory Review
Core: Chapter 1 = complete version done right in one go (rhythm + visuals + real assets complete). No "skeleton version" concept — Chapter 1 must be a user-reviewable prototype.
Why Chapter 1 must be on the main thread:
- It is the first application of the
CHAPTER-CRAFT.mdguidelines with the current theme + current subject matter - If there are blind spots / theme colors or font tokens insufficient, Chapter 1 will expose them — fixing early with human feedback costs the least
- Subsequent chapters (sequential or parallel) will use Chapter 1's code pattern as reference, so Chapter 1 = the "style anchor" of the project (don't force uniformity between chapters, but the chapter itself must be fully convincing)
After completing Chapter 1, you must stop and wait for user review:
Chapter 1 <id> is done. Dev server running at localhost:5173.
Review focus:
□ Is the visual vibe correct? Does it match the expectations of <theme name>?
□ Is the rhythm correct? Any steps too fast / too slow / too thin on info?
□ Are content-driven animations in place? Or are some steps just mindless entrance animations?
□ Dual-source principle: Does the screen have details that "the voiceover doesn't mention but the article can hang"?
□ Anti-AI feel check: Purple-pink gradients / rounded color borders / fake illustrations / emoji overuse?
Tell me what needs fixing. Say "continue" when ready, and I'll proceed with Chapters 2+ in the selected mode.
2.3 Chapters 2~N — According to Selected Mode
Common rules for all modes: Each chapter is developed independently according to CHAPTER-CRAFT.md. Style does not need to be perfectly uniform between chapters — theme colors / font tokens provide visual cohesion; animation / rhythm / visual demonstrations freely expressed per chapter is the design expectation.
Mode A · Default · Chapter-by-Chapter Confirmation
Chapter 2 done → pause and review → OK → Chapter 3 → pause → ... → Chapter N. Each chapter reviewed independently, issues can be fixed anytime, lowest risk, most stable pace. This is the default if the user doesn't explicitly select a mode.
Mode B · Sequential Development After Chapter 1
Chapter 2 → Chapter 3 → ... → Chapter N done sequentially on the main thread, reviewed all at once at the end. Moderate speed, suitable for environments where the agent doesn't support parallel tasks.
Mode C · Parallel Development After Chapter 1 (subagent)
Use subagents to complete Chapters 2~N in parallel. Maximum parallelism controlled by the user ("4 chapters at once" / "2 chapters at once"). Fastest, but style may vary between chapters — this is expected, because:
- Each subagent doesn't see other subagents' output and can't mechanically align
- Chapter code is physically separated (each chapter has its own folder / CSS prefix), they won't interfere
- Theme tokens provide visual cohesion (colors / fonts / hero numbers / cards / divider styles / decorations), preventing severe deviation
- Style variation = the breathing feel of hand-crafted video (multi-voice / multi-perspective)
The parallel subagent prompt must include:
- The current chapter's outline paragraph (with info pool)
- Path to
references/CHAPTER-CRAFT.md(singular mandatory read — visual demonstration requirements + step-by-step reveal + dual-source principle + anti-AI feel + code red lines + completion self-check all in this one file) - Current theme's
theme.jsondescription/mood/bestFor(reference for vibe only; animations / duration / font sizes / emojis are at the chapter agent's discretion) - Chapter 1's code as a "code style" reference (not a "visual copy target")
- Hard rules: Each chapter has its own CSS prefix (
.cd-/.mg-/.pm-/ ...); do not modifychapters.ts; on completion, runnpx tsc --noEmit
Important: Regardless of mode selected, the user can switch modes at any time. After Chapter 2 is OK, the user can say "parallel the rest" / "sequential the rest."
2.4 Implement a Single Chapter (Mandatory Per Chapter)
Detailed guidance in references/CHAPTER-CRAFT.md — single mandatory read entry, covering: visual demonstration requirements / step-by-step reveal / content curation / dual-source principle / basic video demo aesthetics / anti-AI feel / code red lines / completion self-check.
Core Points (detailed in CHAPTER-CRAFT.md):
- Every chapter must have CSS / SVG / Canvas / JS visual demonstrations, no pure-text chapters allowed
- Step-by-step reveal: Lists / multi-item displays must have 1 item = 1 step, forbid showing all at once
- Dual-source principle: Rhythm follows the voiceover script (order cannot be changed), details revisit the original article (info pool + this chapter's article paragraph)
- Go through the completion self-check item by item; if not meeting standards, go back and fix — execute according to the "Mandatory Self-Check Protocol" above (prefer Agent Teams → subAgent → self-check), only then report this chapter's delivery to the user
2.5 Bump STORAGE_KEY After Major Changes
After modifying chapters.ts (adding / deleting / rearranging chapters, or changing narrations.ts length in a chapter), bump STORAGE_KEY in presentation/src/hooks/useStepper.ts (e.g., v4 → v5) to prevent the persisted cursor from landing on a non-existent step.
Checkpoint Audio — Whether to Synthesize Audio (Hard Node)
After Phase 2 ends, you must stop and ask the user:
Web presentation done, {N} chapters / {M} steps. Dev server running at localhost:5173.
Would you like to synthesize audio for "auto-play screen recording"?
✓ Yes → Scan all chapters' narrations.ts to produce audio-segments.json,
call TTS provider to synthesize each step as an mp3 into public/audio/.
After synthesis, use ?auto=1 mode for one-shot screen recording (audio/video naturally synced).
Two built-in providers:
• minimax (mmx-cli) — default, stable for Chinese voice
• openai (OPENAI_API_KEY) — curl-based, most users already have a key
Other backends (ElevenLabs / edge-tts free / macOS say offline /
Azure / Google) — see ready-made snippets in scripts/tts-providers/README.md.
✗ No → Skip Phase 3, go directly to Phase 4 for manual recording + post-production voiceover.
If synthesis → Phase 3. If no → directly Phase 4.
Phase 3 — Audio Synthesis (Optional)
Detailed process in references/AUDIO.md. Simplified:
cd presentation
npm run extract-narrations # Scan all narrations.ts → audio-segments.json
# Let user review audio-segments.json to confirm text correctness
npm run synthesize-audio # Default minimax provider, incremental
# Or use built-in openai (requires OPENAI_API_KEY):
PRESENTATION_TTS=openai npm run synthesize-audio
# Or custom: write a scripts/tts-providers/<name>.sh, see README.md in that directory
After synthesis, inform the user: output location / total segments / any segments with abnormal duration (too long = step needs splitting; too short = text too thin) — give a final chance to calibrate rhythm. Then proceed to Phase 4.
Phase 4 — Screen Recording + Post-production
See details in references/RECORDING.md. Two paths:
| Scenario | Recommended Path |
|---|---|
| Phase 3 audio synthesized | Auto mode one-shot recording: Open localhost:5173/?auto=1 in browser → press SPACE → video plays automatically to the end → stop recording → trim starts/ends → done, no post-production audio sync |
| Phase 3 skipped | Default Manual mode: Click to advance step by step → post-production, add audio in any editing tool |
After Phase 3 / Checkpoint Audio, the agent should proactively tell the user the suitable recording path.
Ten Principles (One-Liner List)
Full expansion in references/CHAPTER-CRAFT.md
Part 0 — Check there when writing chapters; this is just an index.
| # | Principle | One-Liner |
|---|---|---|
| 1 | 16:9 Fixed Stage | Content in 1920×1080 + transform scale, no responsiveness |
| 2 | Global Step Counter | Chapter is a pure function of step, no timers |
| 3 | Each Step Occupies Full Screen | if (step === N) return <FullScene /> |
| 4 | Voiceover Beat = Step | One beat = one step = one focused idea |
| 5 | Hidden Corner Controls | Progress bar / navigator default opacity 0 |
| 6 | Stage Has No Chrome | No header / footer / page number / branding bar |
| 7 | Content-Driven Animation | Find the intrinsic action first; only fallback to entrance animation if none; use persistent micro-animations sparingly |
| 8 | Step-by-Step Reveal | 1 item = 1 step, forbid simultaneous stagger of N items |
| 9 | Same Theme Throughout | No color-switching between chapters; colors / fonts via tokens, other scales free per chapter |
| 10 | Dual-Source Principle | script sets the beat, article determines visual density (landing in the info pool) |
Common User Feedback Quick Reference
Simplified table in references/CHAPTER-CRAFT.md
Part 8 "Common Feedback Quick Reference." Key: First identify the layer (rhythm / visuals / content / code), then modify the smallest slice, don't redo the whole chapter.
Related Resources
Labelled by "when to read" to avoid reading everything at once:
| File | When to Read | Content |
|---|---|---|
references/SCRIPT-STYLE.md | Phase 1.2 mandatory read | Article → voiceover script rules, platform variants |
references/OUTLINE-FORMAT.md | Phase 1.2 mandatory read | outline.md field spec, naming conventions, chapter splits, info pool |
references/CHAPTER-CRAFT.md | Phase 2.4 every chapter single mandatory read entry | Part 0 Ten Principles / Part 1 Start-up 5 Questions / Part 2 Relationship→Action Decision Tree / Part 3 Visual Toolkit / Part 4 Duration / Part 5 Anti-AI Anti-Patterns / Part 6 Code Hard Rules / Part 7 Completion Self-Check / Part 8 Feedback Quick Reference |
references/EXAMPLES/ | Optional — look at structure | Chapter structure examples (hook / list-reveal / case-tech-review); not templates to copy |
references/THEMES.md | When selecting / creating / customizing themes | Complete token contract + built-in theme list + creation process |
references/AUDIO.md | Read only in Phase 3 | Provider-agnostic audio synthesis workflow, built-in minimax usage, provider change path, troubleshooting |
templates/scripts/tts-providers/README.md | When changing / adding 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 synthesis |
themes/ | Browse at Checkpoint Plan / Phase 1.2 | Built-in themes (each with theme.json + tokens.css) |
scripts/scaffold.sh | Run once at Phase 2.1 | One-click project scaffold |