Reference Library Commands

references list          # List all stored references (auto-cleans orphaned entries)
references show <id>     # Show full design report for a reference
references delete <id>   # Delete a reference and its files

Style Profile Commands

profiles list            # List all saved style profiles
profiles show <name>     # Show profile props_override
profiles delete <name>   # Delete a style profile
profiles create <name>   # Create a new style profile interactively

Pre-Workflow Usage

When the user provides a reference video or image alongside a video creation request, extract design patterns before Step 1 and apply them as session overrides. See references/workflow-steps.md → Pre-workflow section for the full extraction flow.

Step 9 Integration

Before choosing visual design in Step 9, check for matching style profiles or reference library entries. Apply the best match as a starting point for Remotion composition props. See references/workflow-steps.md → Step 9 Style Profile Integration for the priority chain.

Auto Update Check

Agent behavior: Check for updates at most once per day (throttled by timestamp file):

STAMP="${CLAUDE_SKILL_DIR}/.last_update_check"
NOW=$(date +%s)
LAST=$(cat "$STAMP" 2>/dev/null || echo 0)
if [ $((NOW - LAST)) -gt 86400 ]; then
  timeout 5 git -C ${CLAUDE_SKILL_DIR} fetch --quiet 2>/dev/null || true
  LOCAL=$(git -C ${CLAUDE_SKILL_DIR} rev-parse HEAD 2>/dev/null)
  REMOTE=$(git -C ${CLAUDE_SKILL_DIR} rev-parse origin/main 2>/dev/null)
  echo "$NOW" > "$STAMP"
  if [ -n "$LOCAL" ] && [ -n "$REMOTE" ] && [ "$LOCAL" != "$REMOTE" ]; then
    echo "UPDATE_AVAILABLE"
  else
    echo "UP_TO_DATE"
  fi
else
  echo "SKIPPED_RECENT_CHECK"
fi

• Update available: Ask user via AskUserQuestion. Yes → git -C ${CLAUDE_SKILL_DIR} pull. No → continue.
• Up to date / Skipped: Continue silently.

Prerequisites Check

!( missing=""; node -v >/dev/null 2>&1 || missing="$missing node"; python3 --version >/dev/null 2>&1 || missing="$missing python3"; ffmpeg -version >/dev/null 2>&1 || missing="$missing ffmpeg"; [ -n "$AZURE_SPEECH_KEY" ] || missing="$missing AZURE_SPEECH_KEY"; if [ -n "$missing" ]; then echo "MISSING:$missing"; else echo "ALL_OK"; fi )

If MISSING reported above, see README.md for full setup instructions (install commands, API key setup, Remotion project init).

Overview

Automated pipeline for professional Bilibili horizontal knowledge videos from a topic.

Target: Bilibili horizontal video (16:9)

• Resolution: 3840×2160 (4K) or 1920×1080 (1080p)
• Style: Clean white (default)

Tech stack: Claude + Azure TTS + Remotion + FFmpeg

Output Specs

| Parameter | Horizontal (16:9) | Vertical (9:16) | |-----------|-------------------|-----------------| | Resolution | 3840×2160 (4K) | 2160×3840 (4K) | | Frame rate | 30 fps | 30 fps | | Encoding | H.264, 16Mbps | H.264, 16Mbps | | Audio | AAC, 192kbps | AAC, 192kbps | | Duration | 1-15 min | 60-90s (highlight) |

Execution Modes

Agent behavior: Detect user intent at workflow start:

• "Make a video about..." / no special instructions → Auto Mode
• "I want to control each step" / mentions interactive → Interactive Mode
• Default: Auto Mode

Auto Mode (Default)

Full pipeline with sensible defaults. Only 1 mandatory stop:

1. Step 10: After 720p preview render — user reviews, confirms before 4K

| Step | Decision | Auto Default | |------|----------|-------------| | 3 | Title position | top-center | | 5 | Media assets | Skip (text-only animations) | | 7 | Thumbnail method | Remotion-generated (16:9 + 4:3) | | 9 | Outro animation | Pre-made MP4 (white/black by theme) | | 9 | Preview method | Preview render (720p, self-validates) | | 12 | Subtitles | Skip | | 14 | Cleanup | Auto-clean temp files |

Users can override any default in their initial request:

• "make a video about AI, burn subtitles" → auto + subtitles on
• "use dark theme, AI thumbnails" → auto + dark + imagen
• "need screenshots" → auto + media collection enabled

Interactive Mode

Prompts at each decision point. Activated by:

• "interactive mode" / "I want to choose each option"
• User explicitly requests control

Workflow State & Resume

Planned feature (not yet implemented). Currently, workflow progress is tracked via Claude's conversation context. If a session is interrupted, re-invoke the skill and Claude will check existing files in videos/{name}/ to determine where to resume.

Technical Rules

Hard constraints for video production — visual design is Claude's creative freedom:

| Rule | Requirement | |------|-------------| | Single Project | All videos under videos/{name}/ in user's Remotion project. NEVER create a new project per video. | | 4K Output | 3840×2160, use scale(2) wrapper over 1920×1080 design space | | Content Width | ≥85% of screen width | | Bottom Safe Zone | Bottom 100px reserved for subtitles | | Audio Sync | All animations driven by timing.json timestamps | | Thumbnail | MUST generate 16:9 (1920×1080) AND 4:3 (1200×900). Title ≥80px bold, high contrast. | | Font | PingFang SC / Noto Sans SC for Chinese text |

Additional Resources

Claude loads these files on demand — do NOT load all at once:

• references/workflow-steps.md: Detailed step-by-step instructions (Steps 1-14). Load at workflow start.
• references/design-guide.md: Visual minimums, typography, layout patterns, checklists. MUST load before Step 9.
• references/troubleshooting.md: Error fixes, BGM options, preference commands, preference learning. Load on error or user request.
• examples/: Real production video projects. Claude may reference these for composition structure and timing.json format.

Directory Structure

project-root/                           # Remotion project root
├── src/remotion/                       # Remotion source
│   ├── compositions/                   # Video composition definitions
│   ├── Root.tsx                        # Remotion entry
│   └── index.ts                        # Exports
│
├── public/                             # Remotion default (unused — use --public-dir videos/{name}/)
│
├── videos/{video-name}/                # Video project assets
│   ├── workflow_state.json             # Workflow progress
│   ├── topic_definition.md             # Step 1
│   ├── topic_research.md               # Step 2
│   ├── podcast.txt                     # Step 4: narration script
│   ├── podcast_audio.wav               # Step 8: TTS audio
│   ├── podcast_audio.srt               # Step 8: subtitles
│   ├── timing.json                     # Step 8: timeline
│   ├── thumbnail_*.png                 # Step 7
│   ├── output.mp4                      # Step 10
│   ├── video_with_bgm.mp4             # Step 11
│   ├── final_video.mp4                 # Step 12: final output
│   └── bgm.mp3                         # Background music
│
└── remotion.config.ts

Important: Always use --public-dir and full output path for Remotion render:

npx remotion render src/remotion/index.ts CompositionId videos/{name}/output.mp4 --public-dir videos/{name}/

Naming Rules

Video name {video-name}: lowercase English, hyphen-separated (e.g., reference-manager-comparison)

Section name {section}: lowercase English, underscore-separated, matches [SECTION:xxx]

Thumbnail naming (16:9 AND 4:3 both required): | Type | 16:9 | 4:3 | |------|------|-----| | Remotion | thumbnail_remotion_16x9.png | thumbnail_remotion_4x3.png | | AI | thumbnail_ai_16x9.png | thumbnail_ai_4x3.png |

Public Directory

Use --public-dir videos/{name}/ for all Remotion commands. Each video's assets (timing.json, podcast_audio.wav, bgm.mp3) stay in its own directory — no copying to public/ needed. This enables parallel renders of different videos.

# All render/studio/still commands use --public-dir
npx remotion studio src/remotion/index.ts --public-dir videos/{name}/
npx remotion render src/remotion/index.ts CompositionId videos/{name}/output.mp4 --public-dir videos/{name}/ --video-bitrate 16M
npx remotion still src/remotion/index.ts Thumbnail16x9 videos/{name}/thumbnail.png --public-dir videos/{name}/

Workflow

Progress Tracking

At Step 1 start:

1. Create videos/{name}/workflow_state.json
2. Use TaskCreate to create tasks per step. Mark in_progress on start, completed on finish.
3. Each step updates BOTH workflow_state.json AND TaskUpdate.

 1. Define topic direction → topic_definition.md
 2. Research topic → topic_research.md
 3. Design video sections (5-7 chapters)
 4. Write narration script → podcast.txt
 5. Collect media assets → media_manifest.json
 6. Generate publish info (Part 1) → publish_info.md
 7. Generate thumbnails (16:9 + 4:3) → thumbnail_*.png
 8. Generate TTS audio → podcast_audio.wav, timing.json
 9. Create Remotion composition + Studio preview
10. Render 4K video → output.mp4
11. Mix background music → video_with_bgm.mp4
12. Add subtitles (optional) → final_video.mp4
13. Complete publish info (Part 2) → chapter timestamps
14. Verify output & cleanup
15. Generate vertical shorts (optional) → shorts/

Validation Checkpoints

After Step 8 (TTS):

• [ ] podcast_audio.wav exists and plays correctly
• [ ] timing.json has all sections with correct timestamps
• [ ] podcast_audio.srt encoding is UTF-8

After Step 10 (Render):

• [ ] output.mp4 resolution is 3840x2160
• [ ] Audio-video sync verified
• [ ] No black frames

Key Commands Reference

See CLAUDE.md for the full command reference (TTS, Remotion, FFmpeg, shorts generation).

User Preference System

Skill learns and applies preferences automatically. See references/troubleshooting.md for commands and learning details.

Storage Files

| File | Purpose | |------|---------| | user_prefs.json | Learned preferences (auto-created from template) | | user_prefs.template.json | Default values | | prefs_schema.json | JSON schema definition |

Priority

Final = merge(Root.tsx defaults < global < topic_patterns[type] < current instructions)

User Commands

| Command | Effect | |---------|--------| | "show preferences" | Show current preferences | | "reset preferences" | Reset to defaults | | "save as X default" | Save to topic_patterns |

Troubleshooting & Preferences

Full reference: Read references/troubleshooting.md on errors, preference questions, or BGM options.

Platform Optimizations

Bilibili:

• Script Structure - Welcome intro + call-to-action outro (一键三连)
• Chapter Timestamps - Auto-generated MM:SS format for B站 chapters
• Thumbnail Generation - AI (imagen/imagenty) or Remotion, auto-generates 16:9 + 4:3 versions
• Visual Style - Bold text, minimal whitespace, high information density
• Publish Info - Title formulas, tag strategies, description templates

YouTube:

• SEO Optimization - Title <70 chars, keyword-rich description, tags and hashtags
• Chapters - Auto-generated YouTube chapter timestamps (first line at 0:00)
• CTA - "Like, Subscribe & Share" text animation or custom

Xiaohongshu (小红书):

• Title - Max 20 chars, punchy and emoji-friendly
• Description - 200-500 chars, 种草/knowledge-sharing style with emoji
• Hashtags - #话题# format (double hash), 5-10 tags
• Thumbnail - 3:4 (1080x1440) for feed optimization
• CTA - "点赞收藏加关注" text animation

Douyin (抖音):

• Format - Vertical shorts only (9:16), no horizontal long-form
• Description - 100-200 chars, casual and conversational with emoji
• Hashtags - #话题 format (single hash), 3-8 tags
• CTA - "点赞关注" text only (no animation)

WeChat Channels (微信视频号):

• Format - Vertical shorts only (9:16), no horizontal long-form
• Description - 100-300 chars, knowledge-sharing style for forwarding
• Hashtags - #话题 format (single hash), 3-8 tags
• CTA - "点赞关注，转发给朋友" text only (no animation)

Workflow

Related Skills

This skill depends on remotion-best-practices and works alongside other optional skills:

• remotion-best-practices - Official Remotion best practices (required, provides core Remotion patterns and guidelines)
• find-skills - Official skill discovery tool (optional, helps find and install additional skills)
• ffmpeg - Advanced audio/video processing (optional)
• imagen / imagenty - AI thumbnail generation (optional)

Requirements

System Requirements

| Software | Version | Purpose | |----------|---------|---------| | macOS / Linux | - | Tested on macOS, Linux compatible | | Python | 3.8+ | TTS script, automation | | Node.js | 18+ | Remotion video rendering | | FFmpeg | 4.0+ | Audio/video processing |

Installation

# macOS
brew install ffmpeg node python3

# Ubuntu/Debian
sudo apt install ffmpeg nodejs python3 python3-pip

# Python dependencies
pip install azure-cognitiveservices-speech dashscope edge-tts requests

Project Setup (Required)

Important: This skill requires a Remotion project as the foundation.

Understanding the components:

| Component | Source | Purpose | |-----------|--------|---------| | Remotion Project | npx create-video | Base framework with src/, public/, package.json | | video-podcast-maker | Claude Code skill | Workflow orchestration (this skill) |

# Step 1: Create a new Remotion project (base framework)
npx create-video@latest my-video-project
cd my-video-project
npm i  # Install Remotion dependencies

# Step 2: Verify installation
npx remotion studio  # Should open browser preview

If you already have a Remotion project:

cd your-existing-project
npm install remotion @remotion/cli @remotion/player zod

API Keys Required

| Service | Purpose | Get Key | |---------|---------|---------| | Azure Speech | TTS audio generation (high quality) | Azure Portal → Speech Services | | Volcengine Doubao Speech | TTS audio generation (alternative backend) | Volcengine Console | | Aliyun CosyVoice | TTS audio generation (alternative backend) | Aliyun Bailian | | Edge TTS | TTS audio generation (default, free, no key needed) | pip install edge-tts | | ElevenLabs | TTS audio generation (highest quality English) | ElevenLabs | | Google Cloud TTS | TTS audio generation (wide language support) | Google Cloud Console | | OpenAI | TTS audio generation (simple API) | OpenAI Platform | | Google Gemini | AI thumbnail generation (optional) | AI Studio | | Aliyun Dashscope | AI thumbnail - Chinese optimized (optional) | Aliyun Bailian |

Environment Variables

Add to ~/.zshrc or ~/.bashrc:

# TTS Backend: edge (default, free), azure, doubao, cosyvoice, elevenlabs, google, openai
export TTS_BACKEND="edge"                            # Default (free), or "azure" / "doubao" / "cosyvoice" / "elevenlabs" / "google" / "openai"

# Azure TTS (high quality)
export AZURE_SPEECH_KEY="your-azure-speech-key"
export AZURE_SPEECH_REGION="eastasia"

# Volcengine Doubao TTS (alternative backend)
export VOLCENGINE_APPID="your-volcengine-appid"
export VOLCENGINE_ACCESS_TOKEN="your-volcengine-access-token"
export VOLCENGINE_CLUSTER="volcano_tts"              # Default cluster, adjust per console config
export VOLCENGINE_VOICE_TYPE="BV001_streaming"       # Adjust per console voice options

# Aliyun CosyVoice TTS (alternative backend) + AI thumbnails
export DASHSCOPE_API_KEY="your-dashscope-api-key"

# Optional: Edge TTS voice override
export EDGE_TTS_VOICE="zh-CN-XiaoxiaoNeural"

# ElevenLabs TTS
export ELEVENLABS_API_KEY="your-elevenlabs-api-key"

# Google Cloud TTS
export GOOGLE_TTS_API_KEY="your-google-tts-api-key"

# OpenAI TTS
export OPENAI_API_KEY="your-openai-api-key"

# Optional: Google Gemini for AI thumbnails
export GEMINI_API_KEY="your-gemini-api-key"

Then reload: source ~/.zshrc

Quick Start

Usage

This skill is designed for use with Claude Code or Opencode. Simply tell Claude:

"Create a video podcast about [your topic]"

Claude will guide you through the entire workflow automatically.

Tips: The quality of first-generation output heavily depends on the model's intelligence and capabilities — the smarter and more advanced the model, the better the results. In our testing, both Codex and Claude Code produce excellent videos on the first try, and OpenCode paired with GLM-5 also delivers solid results. If the initial output isn't perfect, you can preview it in Remotion Studio and ask the coding agent to keep refining until you're satisfied.

Preview & Visual Editing with Remotion Studio

Before rendering the final video, use Remotion Studio to preview and visually edit styles:

npx remotion studio src/remotion/index.ts

This opens a browser-based editor wh