quickdesign

# QuickDesign CLI skill

This skill teaches Claude how to plan and execute AI media generation through the `quickdesign` CLI. The CLI wraps QuickDesign's hosted models (Seedance 2.0 R2V/I2V, Kling, Sora 2, Nano Banana, GPT Image, video upscale) so a Claude session can produce videos and images directly from Bash without managing API keys, polling, or storage upload.

## When to invoke

- **Talking-avatar / UGC video** — "make a 30-second ad where this person says X", "convert this script to a video", "create a creator-selfie clip"
- **Multi-segment promo / explainer** — anything where total speech is >15s (single Seedance segment cap) or where the user wants angle cuts / framing progression
- **Image edit / generation** — angle change, state change, product on white background, lifestyle composite, brand-kit-styled creatives, multi-product reference composition
- **Video upscale** — bring 720p / 1080p output to 1080p / 4K
- **Bulk / batch creative production** — "do this for each of these 5 product photos"

Do NOT use for: pure text generation, code edits, search — those have their own tools.

## Cardinal rules (read first, every time)

These apply to every generation. Breaking any of them produces visible defects.

0. **Default video model = `seedance-2.0-r2v` for ANY UGC / talking-avatar / promo / explainer / multi-scene work, regardless of duration or segment count.** Don't downgrade to `seedance-2.0-i2v` because the script is "short enough" — R2V handles 4-15s single-shot just as well as multi-segment, and going through R2V from the start preserves every primitive this skill depends on (`@Image1` references, multi-`--reference-image`, `--reference-audio` voice continuity). Switch off R2V only on **explicit user opt-in** ("use Sora 2") or if R2V is unavailable in the registry.

   ⚠️ **The name "i2v" (image-to-video) is misleading.** R2V also accepts a single-image-to-video flow — just pass one `--reference-image`. Don't pick i2v because the task is "image-to-video as English". An agent reasoning chain like *"user wants to animate static images → image-to-video → therefore seedance-2.0-i2v"* is the silent regression this rule exists to prevent. Even when you're animating a single banana edit with no speech and no multi-ref needs, R2V is still the default — i2v adds nothing and forfeits the primitives if the next iteration of the task DOES need them.

   See `models/seedance-2.0-r2v.md`.

1. **Use `@Image1` / `@Audio1` / `@Video1` reference labels in prompts, and pass EVERY relevant photo as a separate reference.** Both `nano-banana-2` (image edit) and Seedance 2.0 R2V (video) accept multiple `--reference-image` flags. If the user uploaded a product from two angles, pass both — describing the second one in prose is a regression. Don't re-describe the person, wardrobe, or product in words; that competes with the reference image and causes drift.

   ❌ **Wrong** — verbose verbatim re-description of `@Image1`:
   ```
   Authentic UGC photo of the woman from the reference (long wavy brown
   hair, natural glowy makeup, glossy peach-coral lips, gold hoop earrings,
   pearl choker, soft smile), wearing the beige suede sneakers from the
   second reference, in a cozy minimal bedroom...
   ```
   Banana already SEES her hair / makeup / lips / jewelry in `@Image1` and the sneaker color / silhouette / sole in `@Image2`. Re-describing them tells the model "ignore the references, paint from this prose" — competes with the visual anchor and causes drift.

   ✅ **Right** — labels do the work, prose only describes what's NEW:
   ```
   Edit @Image1: change pose to iPhone mirror selfie. Add a white ribbed
   tank top + oversized baggy jeans. Sneakers matching @Image2 visible at
   the bottom of the frame. Keep face, hair, makeup, jewelry, and
   lighting unchanged from @Image1.
   ```

   See `references/multi-reference-pattern.md` and the per-model card under `models/`.

2. **Multi-segment voice continuity = `--reference-audio` from Seg 1's extracted audio.** Generate Seg 1 first → `ffmpeg -vn -acodec libmp3lame` extracts audio → pass that mp3 as `--reference-audio` to Segs 2..N. Without this, every segment picks a different voice. See `references/voice-continuity.md`.

3. **Suppress the layered music bed and burned subtitles — minimal directive only.** Add two short lines to the prompt: `No music score.` and `No subtitles or on-screen text.` That's it. Do NOT enumerate ambient sounds you want to keep ("street noise, café chatter, espresso machine") — Seedance produces natural ambient on its own; over-prescribing makes audio feel scripted. See `references/no-music-no-subtitles.md`.

4. **For burned-in captions, use `quickdesign video subtitle` AFTER generation.** Never let the video model burn its own captions via the prompt — they hallucinate. The dedicated subtitle endpoint runs real ASR (ElevenLabs) and renders accurate karaoke-style captions. See `references/auto-subtitle.md`.

5. **Confirmation gates — pause before spending credits, even in auto mode.** Auto mode reduces friction for **low-cost reversible work** (file edits, research, planning). Paid AI generation is neither low-cost nor reversible — auto mode does NOT bypass these gates. Always:
   - **Plan summary BEFORE any video generation** (Type / Model / Duration / Cost / Script). Surface it, then either wait for explicit "go" (normal mode) OR proceed immediately while keeping the plan visible above the bash call so the user can kill the task before the spend completes (auto mode). The plan must arrive BEFORE the bash invocation, never after.
   - **Banana edit reference BEFORE feeding it into Seedance R2V** → show the edit, wait for visual approval. Banana ~12cr, Seedance ~250-500cr; a wrong reference auto-chained burns 50× the cost. This gate does NOT compress in auto mode.
   - See `references/confirmation-rules.md` for full auto-mode interplay.

6. **For *choice* gates use the `AskUserQuestion` tool, not free-form prose.** Model pick