promo-video-skill

Turn any codebase into a professional promo video.

One command. Landscape + Portrait. Voiceover included.

---

Point Claude Code at your repo. It scans your codebase, finds your logo, brand colors, and features — then builds an entire animated video with AI voiceover and renders it in both formats, ready to post.

How It Works

  Your Repo                    Claude Code                     Output
 ┌──────────┐    ┌───────────────────────────────┐    ┌─────────────────┐
 │ code     │    │  1. Scan codebase             │    │ landscape.mp4   │
 │ logo     │───>│  2. Creative direction        │───>│ 1920 x 1080     │
 │ readme   │    │  3. Build Remotion scenes     │    ├─────────────────┤
 │ colors   │    │  4. Generate AI voiceover     │    │ portrait.mp4    │
 └──────────┘    │  5. Render + combine audio    │    │ 1080 x 1920     │
                 └───────────────────────────────┘    └─────────────────┘

Quick Start

1. Install the skills

Open any terminal and run:

npx skills add remotion-dev/skills         # Remotion fundamentals (peer dependency)
npx skills add AKCodez/promo-video-skill   # Promo video workflow

This installs two Claude Code skills — one teaches Claude how to write Remotion code, the other teaches Claude how to produce a complete promo video.

2. Get your ElevenLabs API key

Sign up for free at elevenlabs.io → go to Profile → API Keys → copy your key.

Then set it in your environment:

# macOS / Linux
export ELEVENLABS_API_KEY="sk_your_key_here"

# Windows PowerShell
$env:ELEVENLABS_API_KEY = "sk_your_key_here"

3. Open Claude Code in your project

Navigate to the repo you want to create a video for, then launch Claude Code:

cd ~/your-saas-project
claude                            # opens Claude Code CLI

Or open the project folder in VS Code with the Claude Code extension, or use the Claude Code desktop app.

4. Prompt Claude

Once Claude Code is running, just type a prompt. Claude will scan your repo, ask you creative questions, and build everything.

Simple:

Create a promo video for this project

With direction:

Create a 60-second dark mode promo video targeting developers

Detailed:

Create a 90-second promo video for this Chrome extension. Use the Rage Hook 
narrative — open with someone frustrated, then reveal the product. Dark theme, 
dramatic male voice, metallic swoosh transitions.

That's it. Claude handles the rest — scanning your codebase, building scenes, generating voiceover, and rendering both landscape and portrait MP4s.

---

Example Prompts

Different prompts give different results. Here are directions you can give Claude:

What You Say	What You Get
"Create a promo video for this project"	Claude picks everything — scans your repo and makes smart defaults
"30-second social ad, light mode, fast transitions"	Quick punchy ad for Instagram/TikTok
"90-second detailed walkthrough with all features"	Longer format covering every feature
"Use the Rage Hook — someone frustrated then discovers the solution"	Emotional opening with anger → silence → whisper reveal
"Demo First narrative — show the product working immediately"	Opens cold with the most impressive feature
"Dark mode, cinematic, Adam voice, metallic swoosh transitions"	Specific visual + audio direction
"Make the CTA 'Visit fastsolve.app' with the ghost logo"	Specific branding for the closing
"Browse ElevenLabs for a sinister dramatic male voice"	Claude searches voices and generates test samples for you
"Speed up the transitions and make the text bigger in scene 3"	Iterate on an existing video after first render

---

The Pipeline

Phase 0 — Preflight Validates your environment automatically. Node.js, API key, ffmpeg, Whisper — if anything is missing, it tells you exactly how to fix it.	Phase 1 — Brand Discovery Scans your repo for: Product name from package.json, README Logo files (icon.png, logo.svg) Brand colors from CSS, Tailwind config Tech stack from dependencies
Phase 2 — Creative Direction Interactive prompts for: Duration (30s / 60s / 90s) Theme (dark / light) Voice (5 built-in + browse more) Narrative structure Transition style + speed	Phase 3 — Build Creates a full Remotion project with: Spring animations + 3D browser mockups Shared scenes for landscape + portrait 2-4 second scenes optimized for engagement Preview in Remotion Studio before proceeding
Phase 4 — Voiceover Generates AI narration via ElevenLabs with emotional presets per scene. Verifies timing with Whisper. Auto-fixes any overlaps.	Phase 5 — Render Renders both formats, mixes background music, combines audio — outputs two final MP4s ready to post.

---

Voiceover Emotional Presets

The AI voice changes emotion per scene — not one flat tone for the whole video.

Preset	Settings	Use For
Rage	Low stability, high style	Hook frustration — "Are you serious right now?!"
Whisper	Low stability, intimate	Secret reveal — "What if you never had to guess again?"
Confident	Mid stability, balanced	Feature demos — "Smart detection scans instantly"
Warm	High stability, smooth	Social proof — "Join 50,000 users"
Dramatic	Mid stability, high style	CTA — "Try it now. Free."

Narrative Templates

Four proven story structures, each with scene breakdowns and voiceover tone guides:

Template	Arc	Best For
The Rage Hook	Frustration → Silence → Whisper → Reveal → CTA	Products solving a painful problem
The Problem Stack	Pain → Pain → Pain → "What if..." → Solution → CTA	Multiple pain points to stack
The Demo First	Magic moment → "How?" → Features → CTA	Products where the UX sells itself
The Transformation	Before → After → How → Proof → CTA	Workflow improvements

Available Voices

Built-in (Free Tier)

Voice	Style	Best For
Matilda	Warm, confident female	Default — versatile
Rachel	Calm, authoritative female	Corporate, B2B
Daniel	Polished, broadcast male	Advertising, launches
Josh	Friendly, conversational male	Consumer apps
Adam	Deep, dramatic male	Cinematic, intense hooks

Don't see what you want? Say "Browse ElevenLabs voices for a sinister dramatic male voice" and Claude will search the library, generate test samples, and let you audition them.

---

What's Inside

skills/promo-video/
│
├── SKILL.md                     Main skill — 5-phase workflow
├── voiceover.md                 ElevenLabs + Whisper timing guide
├── narrative-templates.md       4 story structures with scene breakdowns
├── multi-format.md              Responsive 16:9 + 9:16 architecture
├── brand-discovery.md           Auto-detect logos, colors, fonts
├── metallic-swoosh.md           Custom metallic shine transition
├── promo-patterns.md            Visual inspiration catalog
│
├── scripts/
│   ├── preflight.ts             Environment validation
│   ├── discover-brand.ts        Repo scanner for brand assets
│   ├── discover-voices.ts       ElevenLabs voice browser + sampler
│   ├── timing-calculator.ts     TransitionSeries duration math
│   └── generate-voiceover.ts    Full voiceover generation pipeline
│
└── music/
    ├── inspired-ambient.mp3     Ambient, atmospheric
    ├── motivational-day.mp3     Commercial, uplifting
    └── upbeat-corporate.mp3     Inspiring, energetic

Utility Scripts

All TypeScript, all cross-platform. Run with npx tsx.

preflight.ts — Environment check

npx tsx scripts/preflight.ts

Validates Node.js version, API key, ffmpeg, Whisper. Prints pass/fail with fix instructions.

discover-brand.ts — Brand scanner

npx tsx scripts/discover-brand.ts ~/path/to/your-repo

Scans a repository and outputs: product name, description, logos, hex colors, URLs, tech stack.

discover-voices.ts — Voice browser

npx tsx scripts/discover-voices.ts --query "confident female" --samples 3

Searches ElevenLabs, generates test MP3s in voice-tests/ for audition.

timing-calculator.ts — Duration math

npx tsx scripts/timing-calculator.ts --scenes "120,90,60,90,90" --transition 12 --fps 30 --target 60

Computes exact duration accounting for TransitionSeries overlaps. Shows scene-by-scene timeline.

generate-voiceover.ts — Full pipeline

npx tsx scripts/generate-voiceover.ts --config voiceover-config.json

Generates per-section audio with emotional presets, concatenates, normalizes, and verifies timing.

---

Prerequisites

Requirement	Required	Install
Node.js 18+	Yes	nodejs.org
Claude Code	Yes	claude.ai/code
remotion-dev/skills	Yes	npx skills add remotion-dev/skills
ElevenLabs API Key	Yes	Free at elevenlabs.io
ffmpeg	Auto	Bundled via bunx remotion ffmpeg
Whisper	Optional	pip install openai-whisper

About the Remotion Skill

This skill depends on remotion-dev/skills — the official Remotion skill with 30+ rule files:

Core	Animations, timing, interpolation, sequencing, compositions
Transitions	Fade, slide, wipe, custom presentations
Media	Images, videos, audio, GIFs, fonts
Advanced	Three.js 3D, charts, text animations, captions
Audio	Sound effects, visualization, voiceover
Tools	FFmpeg, DOM measurement, Tailwind, light leaks

The Remotion skill teaches Claude how to write Remotion code. This skill teaches Claude how to produce a complete promo video.

About ffmpeg

You do not need to install ffmpeg. This skill uses bunx remotion ffmpeg — bundled, cross-platform, zero PATH configuration. Works on Windows, macOS, and Linux out of the box.

---

Tips

• Be specific about your audience. "College students struggling with online quizzes" > "students"
• Pick 3-5 features max. More dilutes the message.
• Use the Rage Hook for consumer products — highest engagement.
• Keep scenes to 2-4 seconds. Shorter = more engaging.
• Preview before voiceover. Run npx remotion studio after building scenes.

Troubleshooting

Problem	Fix
Voiceover overlaps	Claude auto-fixes this — or ask to regenerate
Elements too small	"Scale up the elements" or "make text bigger"
Video feels slow	"Shorter scenes" or "quicker transitions"
Portrait looks cramped	Claude adapts via LayoutContext — request adjustments if needed
ElevenLabs 401	Check API key in environment
Premium voice error	Use one of the 5 built-in voices (free tier)

---

MIT License

Built from real production experience. Every pain point was hit during actual video production and fixed in this skill.

Install · Remotion · ElevenLabs · Claude Code