super-video-maker

name	super-video-maker
description	End-to-end AI video production skill for agentic frameworks. Use when the user asks to make, edit, repurpose, caption, soundtrack, or export videos using HeyGen avatars, Seedance or ByteDance b-roll, OpenAI image generation and editing, AI UGC ads, Remotion, HyperFrames, screen recordings, FFmpeg, captions, ElevenLabs music, Suno, or social-video variants.
metadata	{"requires":{"env":["HEYGEN_API_KEY","HEYGEN_AVATAR_ID","FALAI_API_KEY","OPENAI_API_KEY","ELEVENLABS_API_KEY"]}}

Super Video Maker

What this skill does

Turns a video idea, script, product flow, screen recording, avatar brief, or existing long-form video into polished video assets. The skill can produce:

• Avatar Explainers (avatar-explainer): proof-driven avatar videos with a synthetic presenter, screen recordings/source receipts, UI micro-stories, captions, and action takeaways,
• UGC AI Ads (ugc-ai-ad): paid-social ads with a fictional AI creator, reference-image character consistency, Seedance 2.5 clips, ElevenLabs voice consistency, hook variants, captions, and direct-response CTAs,
• Motion Collage Explainers (motion-collage-explainer): faceless one-idea explainer shorts built from a bold screen-print cutout collage still (gpt-image-2) animated into a living collage with Seedance 2.5, narrated in a calm "In a Nutshell" documentary voice (see MOTION_COLLAGE_STYLE.md),
• avatar videos with HeyGen,
• AI b-roll with Seedance 2.5 through fal.ai,
• generated or edited images with OpenAI image models,
• screen recordings with cursor/event logs,
• motion graphics in Remotion or HyperFrames,
• captions, subtitles, music, and final FFmpeg exports.

Read these files when needed

• VIDEO_COPY_PLAYBOOK.md for the copy layer of EVERY recipe: the four-line spine (one viewer, one promise, one mechanism, one next step), the two-track rule (voice carries the argument, screen carries the evidence, neither repeats the other), on-screen copy craft (kinetic headlines, data badges, ghost titles, end-card offers, the typographic strike), format-by-format arcs, credibility rules, and the copy gate to run before the first paid generation call. Read it BEFORE writing any script, hook, headline, or CTA, and read its section 11 FIRST: a transcribed reference VO in the owner-approved PLAIN REGISTER (zero figures of speech in 70 seconds) plus a before/after table of copy the owner rejected as "too poetic, too conceptual, AI slop". The pointing test lives there: if the viewer cannot point at the noun you just said, rewrite it. Pairs with the copywriting-skill skill, which owns the general voice and rhythm rules.
• SPOKEN_VO_HUMANIZER.md for how a spoken line should SOUND (12 rules for short-form scripts + the banned spoken-AI tells list).
• HOOK_PLAYBOOK_ARTICLE_SPRINT.md for hook families, the angle-before-copy rule, and loop accounting.
• recipes/README.md and tools/video_recipes.py for machine-readable video recipes (list, match, plan, validate).
• REFERENCE.md for provider capabilities and routing decisions.
• FFMPEG_PLAYBOOK.md for exact FFmpeg recipes.
• WORKFLOW_EXAMPLES.md for full production examples.
• REMOTION_VIDEO_GUIDE.md for Remotion motion-design rules.
• TABLETOP_EXPLAINER_PLAYBOOK.md + workflows/tabletop-levels-explainer/ for building tiered "levels-of-X" explainer reels (fictional presenter + first/last-frame craft b-roll + beat-locked switch-assembly).
• LIVING_CANVAS_PLAYBOOK.md + workflows/living-canvas-explainer/ for boutique-grade single-canvas SaaS launch/explainer videos: element-level pacing on one continuous canvas (0-3 hard cuts), VO-word-locked camera choreography over persistent UI cards, causal physics + layout reflow + transformation chains, story cold-opens with emotional VO and comedy timing, three-band music, and a beat-locked SFX bus. Read it BEFORE any "make it feel like a top motion studio" request — every duration, zoom factor, and spring constant is specified.
• HYPERREALISTIC_IMAGE_SOP.md for the 12-part framework that turns a reference image into a photorealistic, non-AI-looking UGC creator prompt. Read it before generating any creator still or hyperrealistic character.
• for the recipe: how to build a bold screen-print cutout collage still with , animate it into a living collage with Seedance 2.5, and narrate it in a calm "In a Nutshell" documentary explainer voice. Read it before making any faceless collage/idiom/concept explainer short.

Operating rules

1. Run a staged pipeline, not random tool calls. Use: intake -> script/shot list -> assets -> assembly -> FFmpeg finishing -> QC -> exports. 1a. Copy is a production gate, not a garnish. Before the first TTS call, clip generation, or timeline build, write the four-line spine from VIDEO_COPY_PLAYBOOK.md (one viewer, one promise, one mechanism, one next step), pick the angle, and run its copy checklist. Voice and screen must never carry the same sentence: mute the video and the story should still track, blank the screen and the argument should still land. This ordering is not stylistic. In VO-locked formats the script IS the timeline, so a script change after the build re-locks every frame number.
2. Confirm paid generation before the first paid call. Show planned providers, number of clips/images, duration, resolution, and likely cost drivers.
3. Prefer skill-local tools. Use files in tools/ before reaching for project-root scripts.
4. Every tool should emit RESULT: {...}. Parse that JSON as the source of truth.
5. Keep job state. Put each run in tmp/video_jobs/<job_id>/ with job_state.json, inputs, intermediates, and final exports.
6. Do not delete intermediate assets until QC passes. Failed video jobs are easier to fix when the raw clips still exist.
7. Never commit secrets or user sessions. Do not publish .env, cookies, generated recordings, private avatars, or downloaded user videos.
8. Make errors user-friendly. Hide raw stack traces from end users, but save detailed logs for debugging.
9. Default to story-first videos. Do not make plain news slideshows. Use: hook -> transparent avatar intro -> news beat -> concrete story/example -> source proof -> action step. 9a. Use avatar-explainer as the default recipe name for the format combining HeyGen avatar narration, screen recordings/source receipts, UI micro-stories, b-roll, captions, and action takeaways.
10. Disclose synthetic presenters via the avatar's own voice. Bake the line "Quick note, this is the digital avatar of " into the script right after the hook. Do NOT prepend a static disclaimer card. If the disclosure is missing from the audio, fall back to a small transparent rounded-pill PNG badge in the top-left corner during the first ~4 seconds (Pillow-rendered: dark navy fill #0A1228 at 96% alpha, 2px brand-orange #FF6B2C outline, 16px accent dot, white sans-serif "Digital avatar of ", 22px corner radius, 50px from each edge). Never use a heavy lower-third in the bottom band — it collides with centered captions. Always include a permanent footer line on the outro card: "Digital avatar of . ".

Standard workflow

Stage 0: Pick a recipe

Before intake, list recipes and match the user goal:

python3 .agents/skills/super-video-maker/tools/video_recipes.py list
python3 .agents/skills/super-video-maker/tools/video_recipes.py match --goal "<user request>"
python3 .agents/skills/super-video-maker/tools/video_recipes.py plan --recipe <recipe_id> --goal "<user request>"

Default routing: news/tutorial masters → avatar-explainer; paid-social creator ads → ugc-ai-ad; SaaS demos → screencast-demo or avatar-product-walkthrough; podcast clips → longform-repurpose; faceless one-idea concept/idiom explainer shorts (cutout collage, "In a Nutshell" docu voice) → motion-collage-explainer.

Stage 1: Intake

Collect:

• target platform: YouTube, TikTok, Reels, Shorts, ads, landing page, course, demo,
• output aspect ratios: 16:9, 9:16, 1:1, 4:5,
• desired duration,
• source assets,
• brand style,
• call to action,
• for ads: product/offer, landing page, target persona, pain point, desired conversion event, proof points, claims/compliance limits, and competitor examples,
• for UGC ads: creator persona, real-person reference image rights, fictional-character direction, voice style, visual seed, voice seed, and number of hook variants,
• whether the user wants avatar, faceless, screencast, or hybrid.

Return a concise plan before generation.

Stage 2: Script and shot list

Create:

• spoken script,
• visual shot list,
• UGC ad angle matrix when ugc-ai-ad is selected,
• source deck (each source asset has one unique editorial job),
• visual job labels for every shot: proof / mechanism / consequence / action / transition,
• b-roll prompts,
• on-screen text,
• caption style,
• music mood,
• export targets.

Script shape:

• Hook (first 5-6 seconds): why the viewer should care, in one breath.
• Casual avatar disclosure (one short clause, immediately after the hook, in the avatar's own voice): "Quick note, this is the digital avatar of , walking you through the update." Never use a static disclaimer slide before the hook.
• News beat: what changed.
• Story/example: a concrete situation that makes the change feel real.
• Source proof: agent-operated browser footage or screenshot showing the source.
• Action step: what the viewer should do next (3 numbered moves works well for an outro card).
• Spoken CTA tail (6-8 seconds, mandatory): the avatar speaks a follow CTA over the outro recap card, e.g. "If this kind of teardown is useful, hit follow over at for more . See you in the next one." This is what gives the master a natural ending instead of a silent dead-air card.

Visual brief shape for every beat:

• Narration: the exact words or Whisper segment.
• Visual job: proof / mechanism / consequence / action / transition.
• Surface: source page, UI, doc, dashboard, calendar, editor, browser tab, etc.
• Before state: what is passive, messy, manual, unknown, or unproven.
• Action/motion: cursor move, highlight, crop, tab switch, card reveal, split-screen, montage, etc.
• After state: what the viewer now understands.
• Reject list: lazy visuals that are banned for this beat (generic person at laptop, same hero page again, abstract AI brain, floating icons, etc.).

UGC AI Ad Recipe (ugc-ai-ad)

Use this recipe when the viewer should feel like a real creator is giving a fast, believable recommendation, demo, complaint, or discovery.

1. Intake the offer. Capture product, ICP, pain, desired action, allowed claims, banned claims, proof assets, landing page, platform, aspect ratio, duration, and target cost/test volume.
2. Write the ad angle matrix. Create 3-5 angle rows, each with: hook family, first-frame text, opening line, core pain, product mechanism, proof point, objection handled, CTA, and compliance risk.
3. Pick the creator. Use a user-provided or licensed real-person photo as a photographic reference only. Define a distinct fictional creator: different name, biography, styling, wardrobe, environment, and enough facial differences to avoid identity recreation.
4. Edit the reference into a new fictional character. Use tools/image_provider.py edit with OpenAI gpt-image-2, quality=high, input_fidelity=high, and the strongest available source image. Prompt for a realistic UGC creator, natural phone-camera texture, believable skin, no beauty-filter look, no brand logos, and no retained identity. Save the approved output as assets/character/creator_hero.png.
5. Generate a reference set. From the approved hero image, create: creator_face.png, creator_medium_phone.png, creator_wide_environment.png, and optionally a 2-3 second idle reference video. Keep these with character_card.json.
6. Lock references and voice. Store voice_seed or voice_id for ElevenLabs. Reuse the same approved reference set for every clip in a batch; vary only shot actions, hook text, and CTA. Seedance itself has no seed input on fal (2.5 or 2.0), so a face is held by the reference images alone; visual_seed is a batch label, not a consistency control.
7. Produce clips with Seedance 2.5 through fal.ai. Use tools/fal_seedance_video.py generate --mode reference plus --reference-image for the approved creator references. Pass --reference-audio when native Seedance audio/lip movement is intentional, or use a separate ElevenLabs voice track for controlled ad narration. Prompt each beat as a phone-native scene: creator talking to camera, holding product, screen demo, over-the-shoulder app use, reaction shot, receipt/proof shot, CTA close.
8. Assemble like a UGC ad. First frame must communicate the hook before the viewer reads the caption. Use jump cuts, pattern interrupts, large bottom captions, product/UI inserts, quick proof overlays, and no dead air.

UGC hook families to use before writing the body:

• Confession: "I almost didn't try this because..."
• Contrarian: "Stop doing if you want ."
• Problem-callout: "If keeps happening, check this first."
• Receipt/proof: "I tested for , here is what changed."
• Demo-first: "Watch what happens when I do ."
• Speedrun: "I fixed in with three steps."
• Before/after: "This was my ; this is it after <product/action>."
• Curiosity gap: "The weird part is not ; it is ."

UGC body patterns:

• Pain -> tiny demo -> payoff -> CTA.
• Old way -> new way -> proof -> CTA.
• Mistake -> correction -> product mechanism -> CTA.
• Skeptic -> test -> result -> objection -> CTA.

Seedance prompt skeleton:

Handheld vertical phone video. Fictional UGC creator from reference images,
same face, same hair, same wardrobe family, natural skin texture, no beauty
filter. <specific beat action>. Real <home office / kitchen / parked car /
desk> environment, natural light, casual speech energy, slight handheld motion,
believable phone-camera exposure. No logos, no subtitles in the footage, no
perfect studio lighting, no face morphing, no extra people.

After HeyGen renders the avatar, immediately:

1. Extract the avatar audio with FFmpeg (-vn -acodec libmp3lame).
2. Transcribe with OpenAI Whisper (response_format=verbose_json, timestamp_granularities=['word','segment']) to get word- and segment-level timestamps.
3. Inspect the segments. If the script is duplicated, set the avatar trim end to the last second of the first unique pass.
4. Build a storyboard.json mapping each segment to a layout (avatar fullscreen / b-roll PiP / browser PiP), a visual job, a surface, a before/action/after description, a source-deck asset, a chapter title, and a source attribution.
5. Use those exact timestamps everywhere downstream — captions, segment cuts, lower-thirds.

Stage 3: Asset generation

Use the routing rules:

• HeyGen for presenter/avatar clips.
• Seedance 2.5 for cinematic b-roll and generated motion.
• Seedance 2.5 reference-image mode for UGC character-consistent clips.
• OpenAI image generation/editing for storyboards, stills, thumbnails, inserts, and fictional UGC creator references.
• agent_browser_recorder.py for coherent agent-operated browser footage.
• screen_recorder.py for lower-level product walkthrough recordings.
• local_explainer_broll.py as a no-credit fallback when fal/Seedance is unavailable.
• ElevenLabs for voiceover and music when available.

Stage 4: Timeline assembly

Choose the composition engine:

• Remotion for React timelines, reusable product mockups, captioned talking head, b-roll overlays, and browser preview.
• HyperFrames for HTML-native timelines, deterministic frame capture, GSAP/Lottie/CSS animations, and agent-friendly browser preview.
• FFmpeg for practical compositing, muxing, chroma key, subtitles, audio, and final platform exports.

Stage 5: QC and export

Always check:

• video has a video stream and expected resolution,
• audio exists when expected,
• duration is within target,
• captions are readable and synced,
• no obvious black frames,
• final codec is compatible: libx264, aac, yuv420p.
• b-roll layout QC contact sheets were reviewed and all non-passing assets were fixed/replaced.

Main tools

python3 .agents/skills/super-video-maker/tools/video_recipes.py list
python3 .agents/skills/super-video-maker/tools/video_recipes.py test
python3 .agents/skills/super-video-maker/tools/heygen_client.py
python3 .agents/skills/super-video-maker/tools/fal_seedance_video.py generate --mode reference --prompt "@Image1 handheld UGC creator..." --duration 7 --resolution 1080p --aspect-ratio 16:9 --reference-image assets/character/creator_hero.png
python3 .agents/skills/super-video-maker/tools/fal_seedance_video.py generate --mode reference --prompt "@Image1 and @Image2 show the same fictional creator. Handheld vertical phone video..." --duration 5 --resolution 720p --aspect-ratio 9:16 --reference-image assets/character/creator_hero.png --reference-image assets/character/creator_medium_phone.png
python3 .agents/skills/super-video-maker/tools/image_provider.py edit --reference-image real_person_reference.jpg --prompt "Create a distinct fictional UGC creator..." --size 1024x1536 --quality high --input-fidelity high --model gpt-image-2
python3 .agents/skills/super-video-maker/tools/agent_browser_recorder.py
python3 .agents/skills/super-video-maker/tools/local_explainer_broll.py
python3 .agents/skills/super-video-maker/tools/screen_recorder.py
python3 .agents/skills/super-video-maker/tools/demo_video_composer.py
python3 .agents/skills/super-video-maker/tools/video_captioner.py
python3 .agents/skills/super-video-maker/tools/ffmpeg_qc.py
python3 .agents/skills/super-video-maker/tools/broll_layout_qc.py

Result contract

Each stage should end with one line:

RESULT: {"status":"succeeded","stage":"asset_generation","job_id":"video_001","artifacts":[{"type":"video","path":"output_videos/clip.mp4"}],"metrics":{"duration_seconds":7,"aspect_ratio":"16:9"},"next_action":"assemble_timeline"}

On failure:

RESULT: {"status":"failed","stage":"asset_generation","error":"friendly explanation","debug_log":"tmp/video_jobs/video_001/log.txt"}

Provider defaults

• Avatar: HeyGen.
• AI video b-roll: fal.ai bytedance/seedance-2.5/reference-to-video. --fast pins to bytedance/seedance-2.0/fast/reference-to-video, since only 2.0 has a distilled tier.
• Images: OpenAI image generation/editing.
• Voice: ElevenLabs.
• Music: ElevenLabs Music first, then Replicate or Suno adapters if configured.
• Programmatic editor: Remotion.
• HTML-native editor: HyperFrames.
• Final render/QC: FFmpeg and ffprobe.

When not to use this skill

• The user only wants a single image.
• The user only wants a plain transcript with no video work.
• The user asks for manual Premiere/DaVinci steps and does not want automation.