moonlight-lupin/agent-skills/clips-studio

Clips Studio

Generate a short video clip through deliberate stages — brainstorm → draft cheaply → produce the final at quality — using fal.ai. The moving-image sibling of image-studio. The point of the staging is cost and control: video is the dearest thing on fal (roughly 10–100× a still), so you lock the idea on a cheap model first, then spend on a quality model only once, on the agreed clip.

This skill generates files locally for the user to review and use. It never posts, publishes, or sends anything as final collateral.

Scope and routing

Use this skill only when all of the following are true:

1. The task is generative video — a clip from a prompt, animating a still, or a camera move over a

still — not slide/deck production, charting, dashboarding, or design-template automation.

1. The user is comfortable with fal.ai egress and paid API usage.
2. The local helper workflow is available, or the user is asking you to prepare the brief for it.

Do not use this skill for:

• Still images (use image-studio), Canva-style templates, slide decks, data charts, dashboards,

flowcharts or diagrams.

• Confidential or sensitive image/document processing.
• Any host environment where a native video-generation tool is explicitly mandated.

Three modes — choose this first

Pick the one that matches what the user has and wants:

• Text-to-video (generate) — a clip from a prompt, with no source image. Best for concept,

abstract/motion-graphic, brand-mood or b-roll-style clips with no still to start from. It invents everything, so it is never the way to depict a real place, product or person — animate a real photo for that.

• Animate a still (animate) — bring an existing image to life: a product turning, people

interacting, a scene, foliage/water/light. The clip animates what is in the frame.

• Adding a new subject to an EMPTY scene (people to a room, product to a set) is a two-step job.

Video models animate what they see; they don't reliably invent believable new subjects. So first add the subject to the still with image-studio (an instruction edit), review it, then animate the populated still here.

• Camera move (camera) — extrapolate a camera motion over a still: a slow push-in, pan,

tilt, shallow orbit or pull-out (a "3D"/parallax feel; an interior "3D view"). The subject can be static; the camera moves. This is the riskiest mode for honesty (it invents unseen geometry) — keep moves gentle and read references/motion-honesty-guide.md first.

All three use the same staging below and the same scripts/falvid.py helper (generate / animate / camera).

Before you start — egress and preflight

Generating a clip sends the prompt (and for animate/camera, the start image you provide) to fal.ai, a third-party US service, and the result clip is downloaded from its CDN. That is external data egress.

Before any API call:

1. Confirm the task is in scope.
2. Confirm explicit user go-ahead for fal.ai egress and paid API usage before the first generation in

a session.

1. Confirm explicit user go-ahead again before the costlier Stage-3 production run — **quote the

estimated cost** (video clips can be several dollars each).

1. Check that scripts/falvid.py exists, dependencies are installed, FAL_KEY is set, and the

working directory is writable.

1. For animate/camera, use only non-confidential images the user has rights to process through

fal.ai.

1. Use the exact output paths printed by falvid.py; do not infer filenames from examples.

Never feed confidential or sensitive imagery to fal.ai — e.g. a private person's photo, confidential documents, or anything under NDA. If the user asks to animate something sensitive, stop and flag the egress issue rather than uploading it.

Brainstorming in Stage 1 is pure chat and has no egress, so you can always draft the brief first and confirm the send afterwards.

Setup needed: a fal.ai account with billing, and the FAL_KEY — either the environment variable, or just saved in a text file in the working folder (any filename, e.g. fal key.txt). The helper finds the key automatically — env var first, then any small text file in the working folder, then the home dir — detecting it by content (a FAL_KEY=your-key line or the raw id:secret key), so don't ask the user for a key before checking; only prompt if none is found. It uses the fal-client package (pip install fal-client requests). If no key is found the helper fails with a clear message — generation cannot proceed without it, but Stage 1 still works. (Keep any key file local; never commit it.)

Stage 1 — Brainstorm the brief (no API call)

A good clip starts from a precise brief, so invest here before spending. Interview the user and agree:

• The source — for animate/camera, which still are we using? (For animate of an empty

scene, has the subject been added via image-studio yet?) For generate, there's no still — agree the scene to describe. Keep any original in _workings/ untouched.

• The motion / subject — name the action, not a mood. "A nice product video" is vague; "the

bottle slowly rotates on a plinth, soft studio light sweeping across the label" is concrete. For camera, name the move in cinematographic terms ("slow dolly push-in", "pan left", "shallow orbit").

• Length — default 5 seconds. Keep it short; cost scales with every second. 4–6s suits a

social/web loop.

• Aspect & orientation — anchor to the destination: 16:9 web/hero, 9:16 reel/story, 1:1 social.

For `animate`/`camera`, match the output to the source's orientation and pass `--aspect` explicitly (see the check below). For generate there's no source, so choose the target aspect.

• Audio — FLUX 3 generates audio by default (native, included free). The script sends

generate_audio=true for FLUX 3 models automatically — pass --no-audio to disable. For non-FLUX-3 models (Kling, Seedance, Veo), audio is off by default — opt in with --audio. So the brief must cover sound for FLUX 3, not just motion. Agree with the user:

• Ambient sound — what's naturally in the scene (rain patter, traffic, birds, machinery hum).
• Music — say "no music" if unwanted, or name the genre/feel ("soft ambient piano", "upbeat

electronic"). Each layer lands separately.

• Speech — a quoted line becomes speech only if a speaker is visible on camera. Without one

it renders as burned-in text. Quote the line, describe the speaker, and add "no on-screen text, no subtitles" to prevent burned-in captions.

• Silence — if the user wants no audio at all, pass --no-audio (FLUX 3) or simply don't pass

--audio (other models).

Aspect & orientation — check the source before you generate (applies to `animate`/`camera`). Compare the source still's orientation to the intended video frame (usually 16:9 for web, 9:16 for reels). If they differ — e.g. a portrait or square phone shot for a 16:9 video — don't just generate:

1. First, ask the user for a properly-oriented photo — a landscape shot for a landscape clip, a

vertical shot for a vertical clip. A source that already matches the target frame is the cleanest, most honest result.

1. If the user wants to proceed with the mismatched source anyway, check in on which approach —

never decide it silently:

• (2) Pillarbox / letterbox — keep the source's orientation and place the clip inside the

target frame with side/top fill (bars, or a soft blur of the same shot). Honest — nothing is invented; you just get bars. Usually a step in the user's video editor.

• (3) Generatively extend (outpaint) the still to the target aspect first, then animate —

full-bleed, but the model invents the surroundings that weren't photographed. Combo with image-studio (an instruction edit at the target --aspect). Two musts before any video spend: (a) ground the extension — ask the user for reference images of what's actually around the subject so the model reconstructs the real context rather than inventing it; (b) confirm the extended still with the user BEFORE animating — take corrections, re-edit, approve, then animate. Illustrative only; never present it as the real setting.

1. Never (1) force-crop to the target aspect — on a mismatched source the model centre-crops and

discards most of the subject (a tall building loses its top and bottom). It is off the table.

When the orientation does match, still pass --aspect to match the source so the helper doesn't fall back to 16:9 and crop.

Save the agreed brief to _workings/ (for example _workings/brief_[slug].md) so the run is auditable. Keep prompts free of confidential detail. This step replaces a cheap prototype for the idea — confirm the brief (and the start image, for `animate`/`camera`) before the first paid call.

Prompting craft. Read references/video-prompting-techniques.md before the first generation in a session — it covers grounding real subjects, audio layer control, multi-shot syntax, speech vs burned-in text, and continuation/chaining. These techniques work across all fal.ai video models, not just one. The short version: write plain prose (not keyword tags), ground anything with a real checkable appearance, and specify what matters — what you leave out is the model's call. For a start frame that needs exact in-image text (title card, poster, sign with bilingual 中文/English strings), generate the still first via image-studio's Layout-controlled generation — MOSS-Image section (references/moss-layout.md, compiled by scripts/moss_compile_prompt.py) before animating — video models cannot take JSON layouts and burn in text unreliably.

Stage 2 — Draft cheaply

Render a draft on FLUX 3 Draft (cheap, HD only, native audio included) so you can react for a fraction of the full cost — $0.06/s vs $0.17/s for the full render.

• `animate` — default FLUX 3 Image-to-Video Draft

(blackforestlabs/flux-3/image-to-video/draft, ~$0.06/s → ~$0.30 for 5s, native audio):

``bash python scripts/falvid.py animate \ --prompt "[the agreed motion, including audio description]" \ --image _workings/[source-still].png \ --duration 5 --aspect 16:9 \ --run-log _workings/run-log_[slug].md \ --out-dir _workings --name vid_[slug]_draft ``

• `generate` (text-to-video) — default FLUX 3 Text-to-Video Draft

(blackforestlabs/flux-3/text-to-video/draft, ~$0.06/s → ~$0.30 for 5s, native audio):

``bash python scripts/falvid.py generate \ --prompt "[the scene to create, including audio description]" \ --duration 5 --aspect 16:9 \ --out-dir _workings --name vid_[slug]_draft ``

• `camera` — default Seedance 1.5 Pro (unchanged — strongest camera control); --move offers

gentle presets (push-in, pull-out, pan-left/right, tilt-up/down, orbit, crane-up), and --static locks the camera entirely:

``bash python scripts/falvid.py camera --move push-in \ --image _workings/[still].png --duration 5 --aspect 16:9 \ --out-dir _workings --name vid_[slug]_draft ``

Save the draft's seed — it's printed in the run log and cost log. You need it for Draft Enhance (Stage 3) to re-render the same motion at full quality.