Educational Video Creator
Create professional educational videos with Kurzgesagt/回形针 visual style using Remotion.
Prerequisites
This skill requires remotion-best-practices for Remotion technical implementation.
Check and install (MUST complete before Phase 1):
npx skills list 2>/dev/null | grep remotion-best-practices || npx skills add https://github.com/remotion-dev/skills --skill remotion-best-practices
Once installed, read the remotion-best-practices skill to load Remotion API details into context. This is essential — without it, Phase 4 code will have incorrect Remotion API usage.
External dependencies (needed for Phase 4.5 audio generation):
brew install ffmpeg
pip install edge-tts
Project Setup
This skill creates videos in a dedicated remotion_video subdirectory within the current workspace.
First-time setup (recommended — non-interactive):
mkdir -p remotion_video
cd remotion_video
npm init -y
npm install remotion @remotion/cli @remotion/google-fonts @remotion/transitions react react-dom
npm install -D typescript @types/react
mkdir -p src public/audio/narration
Then create the required entry files:
src/Root.tsx — Main composition registrysrc/index.ts — Remotion entry point with registerRoot(Root)remotion.config.ts — Remotion configurationtsconfig.json — TypeScript config
Alternative (interactive — may block in automated environments):
mkdir -p remotion_video && cd remotion_video
npx create-video@latest --blank
npm install
Note: npx create-video may prompt for project name, package manager, etc. In CLI/automation contexts, use the non-interactive method above to avoid blocking.
Existing project:
cd remotion_video
npm install
Project structure:
your-workspace/
├── remotion_video/ # Video project root
│ ├── src/
│ │ ├── Root.tsx # Main composition registry
│ │ └── YourVideo/ # Video-specific components
│ │ ├── index.tsx
│ │ ├── scenes/
│ │ └── components/
│ ├── public/ # Static assets
│ └── package.json
└── ... (other workspace files)
Quick Start
- Setup project → create
remotion_video directory if needed
- Gather requirements → confirm topic, audience, duration
- Write script → complete narrative with story arc and pacing
- Create storyboard → break script into visual scenes with animation specs
- Design visuals → apply style guide, create SVG components
- Implement animations → code scenes in Remotion
- Quality assurance → auto-check, auto-fix, auto-start preview
⚠️ Context Recovery Protocol
Every conversation turn may follow a context loss (compaction, new session). Before doing ANY work:
- Check if
remotion_video/PROGRESS.md exists
- If YES → Read it completely to determine current phase and last completed step
- If NO → This is a new project, proceed to Phase 1
- Read supporting files referenced in PROGRESS.md (only if that phase is marked complete):
remotion_video/script.md (if Phase 1.5+ completed)remotion_video/storyboard.md (if Phase 2+ completed)src/<Composition>/constants.ts (if Phase 3+ completed — contains COLORS, SCENES, NARRATION, AUDIO_SEGMENTS)
- Verify files listed in "Files Created" section actually exist on disk
- Resume from the first unchecked item in the current phase
Skipping this protocol causes repeated work or file corruption. Always run it first.
Progress Tracking — Mandatory Protocol
⚠️ This protocol is NON-NEGOTIABLE. Skipping updates causes context loss and repeated work.
Maintain remotion_video/PROGRESS.md using progress-template.md. Create it at Phase 1 start. Log decisions in the Decisions table and add every created file to "Files Created".
Checkpoint Rule
Every time you complete a checkbox item in PROGRESS.md, you MUST immediately:
- Mark the item
[x] and add brief notes
- Update the "Current State" section (Current Phase + Current Step)
- Then — and only then — proceed to the next item
Do NOT batch multiple items. One item done → one update → next item.
Phase Transition Gate
Before starting any new Phase, you MUST:
- Read
PROGRESS.md and verify ALL items in the previous phase are [x]
- Update "Current Phase" to the new phase
- If any previous item is unchecked, complete it first
Workflow
Phase 1: Requirements Gathering
⚠️ First: Complete the Prerequisites section (install remotion-best-practices skill and read it). Then create remotion_video/PROGRESS.md from progress-template.md and fill in Project Info.
Before starting, confirm these essential details with the user:
- Topic: What concept/subject to explain?
- Audience: Who is watching? (children/adults, beginners/experts)
- Language: Chinese/English/other?
- Duration: Short (1-3min), Medium (3-5min), or Long (5-10min)?
- Key points: What must the viewer learn?
For detailed question templates, see requirements-guide.md.
Phase 1.5: Script Writing
⚠️ Checkpoint Rule active: After completing EACH checkbox item for this phase, immediately update PROGRESS.md. Do not batch updates.
Write a complete narrative script before designing the storyboard. This phase focuses purely on storytelling — what to say and how to say it well — without worrying about visual specs, frame numbers, or animation parameters.
IMPORTANT: Write the FULL narration text — every word that will be spoken. Do NOT write summaries, bullet points, or placeholders. The script is the final spoken content.
The script must include:
- Core message — one-line summary, learning objectives
- Narrative strategy — apply techniques from script-and-narration.md:
- Entry angle (question / scenario / challenge / story)
- Core metaphor that runs through the entire video
- Knowledge scaffolding order (what depends on what)
- Emotional curve (curiosity → understanding → wonder → satisfaction)
- Full narration text — complete word-for-word script for every chapter:
- Include emphasis markers (bold for stress, italic for softer tone)
- Mark pauses with
[.] (short), [..] (medium), [...] (long), [PAUSE] or [BEAT] (dramatic) — see script-and-narration.md Part 3 for duration semantics
- Add visual intents after each chapter (1-2 sentences describing what viewers should see — enough for Phase 2 to design scenes, but no animation specs)
- Pacing notes — where to speed up, slow down, and pause
- Self-review — run through the checklist in script-and-narration.md before presenting to user
Quality gate: Present the complete script to the user for approval. Do NOT proceed to Phase 2 until the user explicitly approves the narrative.
Why script first:
- Separates "what to tell" from "how to show" — two different creative activities
- LLM produces better narratives when not simultaneously calculating frame ranges
- Pure text is cheap to iterate; storyboard with animation specs is expensive to revise
- Users can easily review "is the story good?" without wading through technical details
Output: Save the approved script as remotion_video/script.md
See script-and-narration.md for video structure templates, narrative techniques, writing techniques, and TTS notes.
Phase 2: Storyboard Design
⚠️ Checkpoint Rule active: After completing EACH checkbox item for this phase, immediately update PROGRESS.md. Do not batch updates.
Convert the approved script into a production-ready storyboard. The script provides what to say; the storyboard defines how to show it.
Input: Completed script (approved in Phase 1.5)
Tasks:
- Break script chapters into visual scenes (5-15 scenes)
- Assign narration text from the script to each scene
- Design visual layers for each scene (background / midground / foreground / UI)
- Add frame-level animation specifications (spring, easing, timing)
- Define visual-narration sync points
- Plan the asset inventory (SVG components, colors, typography)
The cognitive load is much lower than creating everything from scratch — the narrative is already decided, so you only need to focus on visual execution.
Output: Save the completed storyboard as remotion_video/storyboard.md for design traceability and iteration reference.
See storyboard-template.md for templates.
See script-and-narration.md Part 4 for subtitle formatting and TTS notes.
Phase 3: Visual Design
⚠️ Checkpoint Rule active: After completing EACH checkbox item for this phase, immediately update PROGRESS.md. Do not batch updates.
Apply the Kurzgesagt/回形针 style. Concrete steps:
- Choose color palette — Select from design-tokens.ts Section 1 or create a custom palette matching the topic
- Create
constants.ts — Define COLORS, TYPOGRAPHY, SCENES, NARRATION, and estimated AUDIO_SEGMENTS following design-tokens.ts Section 3
- Set up fonts — Use Remotion's
loadFont() from @remotion/google-fonts (see design-tokens.ts Section 2 for reference)
- Create shared SVG components — Build reusable visual elements (icons, illustrations, decorative elements) following svg-components.md
- Design scene layouts — Plan visual layers (background / midground / foreground / UI) per scene following visual-principles.md
Style principles:
- Flat design with subtle gradients
- Bold, saturated color palette
- Geometric shapes with rounded corners (rx/ry)
- Clean sans-serif typography
See style-guide.md for complete visual standards.
See visual-principles.md for composition and layout.
Phase 4: Animation Production
⚠️ Checkpoint Rule active: After completing EACH checkbox item for this phase, immediately update PROGRESS.md. Do not batch updates. Log key file paths in "Files Created".
Implement scenes using Remotion:
- Create SVG components for visual elements
- Use
useCurrentFrame() for all animations
- Apply appropriate easing (spring for natural motion)
- Add scene transitions
Subtitle & narration rules (critical for Phase 4.5 compatibility):
- All narration text must be stored in the
NARRATION object in constants.ts — never hardcode text directly in scene TSX files
- Create an estimated
AUDIO_SEGMENTS in constants.ts with approximate timing. Phase 4.5 will overwrite it with real audio-based timing
- Subtitle components must reference
AUDIO_SEGMENTS.sceneKey — never use inline segment arrays with hardcoded frame numbers
AUDIO_SEGMENTS 中的 startFrame/endFrame 必须使用场景本地帧号（每个场景从 SCENE_PAD=15 开始），不是全局帧号。因为 AudioLayer 和 SubtitleSequence 都在场景的 <Sequence> 内部运行，useCurrentFrame() 返回的是本地帧号。如果使用全局帧号，后续场景的字幕会延迟或完全不显示- This ensures
rebuild-timeline.ts --write in Phase 4.5 can update timing without modifying any scene files
Visual-narration alignment rules (prevents animation-subtitle desync):
- 每个与旁白内容对应的视觉元素（图标出现、箭头展开、图表绘制等），其
startFrame 必须从 AUDIO_SEGMENTS 对应段的 startFrame 派生，不能凭"视觉节奏"硬编码
- 正确模式：
const liftArrowStart = AUDIO_SEGMENTS.forces[0].startFrame;（升力箭头在旁白说"升力"时出现）
- 错误模式：
const liftArrowStart = 30;（凭感觉写的帧数，和旁白无关）
- 纯装饰性动画（背景粒子、环境氛围）不受此约束，可以自由定时
- Phase 4 使用估算 AUDIO_SEGMENTS；Phase 4.5 rebuild-timeline 更新真实时间后，因为代码引用的是变量而非硬编码数字，视觉动画会自动同步
- 参考 animation-guide.md "Narration-Synced Animation" 章节的实现模式
Element sizing rules (prevents "Thumbnail Syndrome" — tiny elements on a large canvas):
Background rules (prevents transparent/checkerboard frames during transitions):
- The main composition must have a persistent
<AbsoluteFill> background layer (using COLORS.background) that sits behind all scenes and never participates in transitions
- Each scene component must also have its own solid background as the first child element
- During
fade() transitions, both scenes have reduced opacity — without a persistent background, transparent frames appear as a checkerboard pattern in preview and black in renders
- See animation-guide.md "Preventing Transparent Frames" for the implementation pattern
Visual richness rules (prevents PPT-like output):
- 每个场景必须有至少一个 非文字的视觉主体元素（SVG 插画、图表、动画图形等）。纯文字标签 + 方块不是合格的视觉内容
- 流程图/因果链必须用 图标或插画 配合文字，不能只用纯色方块装文字。参考 svg-components.md "Illustrated Flow Node" 模式
- 每个场景应有 环境氛围层（粒子、光晕、纹理等），参考 style-guide.md Ambient Effects 章节
- SVG 插画应体现 Kurzgesagt 风格：圆角几何形状（rx/ry）、扁平化但有层次（多 path 叠加）、柔和渐变（linearGradient/radialGradient）、适当描边
- 参考 visual-principles.md "Show, Don't Tell" 原则：能用图示表达的概念不要用文字方块
- 参考 scene-template.tsx 中 ForceDiagramScene 的 SVG 飞机插画作为具象插画的最低质量标准
Color rules (critical for Phase 5 style-scan compliance):
- All colors must be referenced via the
COLORS object from constants.ts (e.g., COLORS.accent.rose) — never write hex values directly in TSX files
- The only exception is
rgba() for opacity variations (e.g., rgba(0, 0, 0, 0.7) for subtitle backgrounds)
- This prevents the common issue where style-scan reports dozens of "color not in approved palette" warnings
See design-tokens.ts Section 3 for the complete constants.ts structure (COLORS, SCENES, NARRATION, AUDIO_SEGMENTS, font loading).
See svg-components.md for component patterns.
See animation-guide.md for timing and easing.
Phase 4.5: Audio Genera
