quickdesign

QuickDesign CLI スキル

このスキルでは、quickdesign CLI を使って AI メディア生成を計画し、実行する方法を Claude に教えます。この CLI は QuickDesign のホスト型モデル（Seedance 2.0 R2V/I2V、Kling、Sora 2、Nano Banana、GPT Image、動画アップスケーリング）をラップするため、Claude のセッションから API キーの管理、ポーリング、ストレージへのアップロードを行わずに、Bash から直接動画や画像を生成できます。

呼び出すタイミング

• トーキングアバター／UGC 動画 — 「この人物が X と話す 30 秒の広告を作って」「この台本を動画にして」「クリエイターの自撮り風クリップを作って」
• 複数セグメントのプロモーション／解説動画 — 発話の合計が 15 秒を超える場合（Seedance の 1 セグメントあたりの上限）、またはユーザーがアングルの切り替え／フレーミングの展開を希望する場合
• 画像の編集／生成 — アングルの変更、状態の変更、白背景の商品画像、ライフスタイル合成、ブランドキットに合わせたクリエイティブ、複数商品の参照画像を使った合成
• 動画のアップスケーリング — 720p／1080p の出力を 1080p／4K にする
• クリエイティブの一括／バッチ制作 — 「この 5 枚の商品写真それぞれについて作って」

次の用途には使用しないでください：テキストのみの生成、コードの編集、検索 — それぞれ専用のツールがあります。

絶対に守るルール（毎回、最初に読む）

これらはすべての生成に適用されます。どれかに違反すると、目に見える不具合が発生します。

0. デフォルトの動画モデルは、尺やセグメント数に関係なく、あらゆる UGC／トーキングアバター／プロモーション／解説動画／マルチシーン制作で seedance-2.0-r2v です。 台本が「十分短い」という理由で seedance-2.0-i2v に切り替えないでください。R2V は 4～15 秒のワンショットにもマルチセグメントと同様に対応でき、最初から R2V を使うことで、このスキルが依存するすべての機能（@Image1 参照、複数の --reference-image、--reference-audio による音声の一貫性）を維持できます。R2V から切り替えるのは、ユーザーが明示的に希望した場合（「Sora 2 を使って」）か、レジストリで R2V が利用できない場合のみです。

   ⚠️ 「i2v」（image-to-video）という名前は誤解を招きます。 R2V も単一画像から動画を生成できます。--reference-image を 1 つ渡すだけです。「英語でいう image-to-video」のタスクだからという理由で i2v を選ばないでください。「ユーザーは静止画像を動かしたい → image-to-video → だから seedance-2.0-i2v」 のようなエージェントの推論は、このルールで防ごうとしている気付かれにくい後退です。音声も複数参照の必要もなく、バナナの編集を 1 枚だけアニメーション化する場合でも、デフォルトは R2V です。i2v では何も追加されず、タスクの次の反復で必要になる可能性がある機能を失います。

   models/seedance-2.0-r2v.md を参照してください。

1. プロンプトでは @Image1／@Audio1／@Video1 の参照ラベルを使い、関連する写真はすべて個別の参照として渡してください。 nano-banana-2（画像編集）と Seedance 2.0 R2V（動画）は、どちらも複数の --reference-image フラグを受け付けます。ユーザーが商品を 2 つのアングルから撮影した画像をアップロードした場合は、両方を渡してください。2 枚目の説明を文章で済ませるのは後退です。人物、衣装、商品を言葉で再説明しないでください。参照画像と競合し、ずれが生じます。

   ❌ 誤り — @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 はすでに @Image1 の髪、メイク、唇、アクセサリーと、@Image2 のスニーカーの色、シルエット、ソールを認識しています。それらを再説明すると、モデルに「参照画像を無視して、この文章から描く」よう指示することになり、視覚的な基準と競合してずれが生じます。

   ✅ 正しい — ラベルに任せ、文章では新しい要素だけを説明する：

   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.
   

   references/multi-reference-pattern.md と models/ 内の各モデルのカードを参照してください。

2. 複数セグメント間で音声の一貫性を保つには、セグメント 1 から抽出した音声を --reference-audio に指定します。 まずセグメント 1 を生成し、ffmpeg -vn -acodec libmp3lame で音声を抽出して、その mp3 をセグメント 2 から N の --reference-audio に渡します。これを行わないと、セグメントごとに異なる音声が選ばれます。references/voice-continuity.md を参照してください。

3. 重ねた音楽と焼き込み字幕を抑える — 指示は最小限にします。 プロンプトに短い行を2つ追加します。No music score. と No subtitles or on-screen text. だけです。残したい環境音（「街の騒音、カフェの話し声、エスプレッソマシン」など）を列挙しないでください。Seedance は自然な環境音を自動で生成します。指示を詰め込みすぎると、音声が台本どおりのように感じられます。references/no-music-no-subtitles.md を参照してください。

4. 焼き込み字幕には、生成後に quickdesign video subtitle を使います。 プロンプトで動画モデルに字幕を焼き込ませないでください。字幕が幻覚されることがあります。専用の字幕エンドポイントは実際の ASR（ElevenLabs）を実行し、正確なカラオケ風字幕をレンダリングします。references/auto-subtitle.md を参照してください。

5. 確認ゲート — 自動モードでも、クレジットを消費する前に一時停止します。 自動モードで手間を減らせるのは、低コストで取り消し可能な作業（ファイル編集、調査、計画）です。有料の AI 生成は低コストでも取り消し可能でもありません。自動モードでも、これらのゲートは省略できません。必ず次のとおりにします。

   • 動画を生成する前に、計画の概要を提示します（種類／モデル／長さ／コスト／スクリプト）。概要を提示したうえで、明示的な「実行」の返答を待つ（通常モード）か、bash 呼び出しの前に計画を見える状態にしたまま、支出が完了する前にユーザーがタスクを中止できるよう、ただちに実行します（自動モード）。計画は bash の呼び出しより前に提示する必要があります。実行後の提示ではいけません。
   • Banana の編集結果を Seedance R2V に渡す前に確認します → 編集結果を見せ、視覚的な承認を待ちます。Banana は約12cr、Seedance は約250～500crです。誤った参照画像を自動連携すると、50倍のコストがかかります。このゲートは自動モードでも省略できません。
   • 自動モードとの連携について詳しくは、references/confirmation-rules.md を参照してください。

6. 選択が必要なゲートでは、自由形式の文章ではなく AskUserQuestion ツールを使います。 モデルの選択、トランジションのスタイル、解像度、Banana の編集結果の承認／再生成／キャンセルでは、選択肢を構造化して AskUserQuestion を呼び出し、推奨案を先頭に (Recommended) と付けて示します。references/confirmation-rules.md を参照してください。

7. アバターが提供されていて、設定を変更しない場合は、アバターを編集してください。再生成してはいけません。 Banana に対するコンポーズ形式のプロンプト（「縦長の 9:16 UGC セルフィーのフレームを構成して…」「クリエイターのセルフィー風シーンを生成して…」など）を使うと、モデルはアバターを参考にして新しい AI 風の画像を生成します。その結果、元画像の照明、粒子感、ローファイな本物らしさが失われます。実際のクリエイターが編集したセルフィーではなく、合成画像のような仕上がりになります。編集を指示する動詞（Edit @Image1: add ...、Take @Image1 as-is and only change ...、Keep every pixel of @Image1 except [region]）を使い、参照画像ですでに示されているシーン要素を重ねて列挙せず、「photo-realistic」「studio quality」「8K」などの品質向上を示す言葉をプロンプトから取り除きます。これらは再生成を引き起こします。references/avatar-edit-not-regenerate.md を参照してください。

8. UGC 動画では、話す動画にするか無音にするかを提示します。黙って選んではいけません。 「UGC 動画」は曖昧です。スクリプトに沿った、音声とリップシンクを含むクリエイターの発話動画の場合もあれば、動きだけの映像（OOTD のお披露目、B ロール、後からテキストを重ねるアニメーション静止画）の場合もあります。どちらも正当なクリエイティブ形式です。エージェントが黙ってどちらかを選んではいけません。

   • 発話を強く示す表現（そのまま進めます）：ユーザーが「talking-avatar」「creator says」「voiceover」「explainer」「ad with script」と書いている、または自分でスクリプトを提示している場合です。スクリプトを作成し、計画の概要に含め、generate_audio: true と引用符で囲んだセリフをインラインで指定して生成します。
   • 無音を強く示す表現（そのまま進めます）：ユーザーが「OOTD reveal」「motion only」「no audio」「B-roll」「Pinterest aesthetic」と書いている、または静止画をアニメーション化したリールを希望している場合です。
   • 「UGC video」／「promo video」／「ad video」のように曖昧な場合 — 話す形式（4～8語のフック案を含む）か、無音＋後からテキストを重ねる形式の2つの選択肢を提示して AskUserQuestion を呼び出します。ユーザーの依頼内容により合うほうを推奨します。黙ってどちらかをデフォルトにしてはいけません。 SPOKEN が選択されている場合: プロンプトに引用された発話がない状態で生成を開始しないでください。ユーザーが発話を用意していない場合は、ブリーフに合う 4～12 秒の会話を下書きし、プラン概要に提示してから進めます。一般的なアクションプロンプトだけで引用された発話なしに生成すると、無音の動画、またはモデルが意味不明な音素を口走る動画になり、クレジットを浪費します。

   語数 → 尺の計算については references/script-and-duration.md を参照してください。

9. マルチセグメントのプランは、視覚的な承認のために Seg 1 の後で STOP します — ユーザーが Seg 1 が正しく仕上がったと確認するまで、Seg 2..N を展開しないでください。 音声の連続性は --reference-audio を介して Seg 1 の音声を後続のすべてのセグメントに固定します。Seg 1 の声が違う、アバターのアイデンティティが違う、単語の発音が誤っている、またはブランドから外れたフレーミングである場合、並列な Seg 2..N はすべてその欠陥を継承します。4 セグメントのプランで 1 セグメントあたり約 250cr = 約 1000cr です。壊れた Seg 1 を自動で展開すると、費やす必要のなかった約 750cr を消費します。

   フローは次のとおりです:

   1. プラン概要 → ユーザーが承認 (ルール 5)。
   2. Seg 1 のみをレンダリング。
   3. Seg 1 の動画 URL をチャットに提示 + AskUserQuestion を次のオプションで呼び出す:
      • 問題ない — Seg 2..N をレンダリング (Seg 1 がクリーンな場合は推奨)
      • Seg 1 を再レンダリング (プロンプト / リファレンス / 尺を調整)
      • マルチセグメントのプランをキャンセル
   4. 「問題ない」の場合のみ → 抽出した音声を使って Seg 2..N を並列で展開。

   このゲートは自動モードでは圧縮されません。Seg 1 → Seg N の消費倍率は、ユーザーがどれだけ辛抱強くても変わりません。正規のマルチセグメントフローについては pipelines/ugc-video.md を参照してください。

10. カメラは固定したままです。ユーザーが明示的に要求しない限り、アングル / フレーミングを変えないでください。 ドキュメンタリースタイルの UGC (街頭インタビュー、キッチンデモ、創業者 POV、顧客の証言、vlog スタイル) は、マルチアングルのカット割りではなく、ひとつの連続したカメラ視点として読まれます。デフォルトは次のとおりです: 同じフレーミング (例: ミッドショットのアイレベル)、同じ距離、すべてのセグメントでアバターがほぼ同じ位置。セグメント間の「トランジション」は、アバターのジェスチャー / セリフ / 微表情であり、アングルのカットではありません。

    ❌ 誤ったデフォルト (無言の回帰 — UGC の真正性を破壊する「撮影監督による撮影」感を生み出します):

    • Seg 1 ミッドショット → Seg 2 肩越し → Seg 3 クローズアップ
    • 「話者にゆっくりプッシュイン」
    • 「オチで製品のクローズアップにカット」
    • 各 nano-banana-2 セグメントの ref で同じ人物の異なるアングルを使用

    ✅ 正しいデフォルト (UGC の真正性が保たれます):

    • すべてのセグメントで同じソースフレーム、またはほぼ同一のアングル / ライティング。セグメント間で変わるのは、アバターの手の位置、視線、表情だけです。

    マルチアングルに切り替えるのは、ユーザーが明示的に要求した場合のみです: 「各セグメントでアングルを交互に」、「フックでシネマティックにクローズアップへカット」、「製品の肩越しショットを含める」、「スタジオスタイルのマルチカム UGC」。判断に迷う場合は、AskUserQuestion で尋ねてください: 固定カメラ (ドキュメンタリー UGC に推奨) / マルチアングル (シネマティックなカット)。

    静的なフレーミングと記述されたカメラモーションに関する関連ルールについては references/first-frame-not-camera-motion.md を参照してください。

11. ユーザーが提供したすべてのリファレンスを精査してください — UGC には製品だけでは不十分です。 ブリーフが「この製品の UGC 動画を作る」であり、ユーザーが製品写真のみを提供した場合は、生成する前に STOP してください。Seedance R2V には次のアンカーとなるリファレンスが必要です: 製品、アバター / クリエイター (顔、体格、雰囲気)、シーン / ロケーション (キッチン、バスルーム、ジム、歩道)。散文で製品を詳細に説明することはできますが、アバターを散文だけで説明すると、Seedance はありふれた見た目の人物 — 多くの場合、20 代の合成的な印象の白人女性 — をハルシネートし、シーンはブランドの世界ではなくストックの B ロールとして読まれます。その結果は「作られていない感」の基準を満たしません。 生成する前に、提供されたメディアを確認します。

    • 製品画像 — ほとんどの場合、提供されています。--reference-image として渡し、プロンプト内では @Image1 とラベル付けします。
    • アバター／クリエイター画像 — ユーザーが提供した場合は、別の --reference-image として渡し、@Image2 とラベル付けします。提供されていない場合は、生成前に AskUserQuestion を呼び出します。選択肢は次のとおりです。クリエイターの顔写真をアップロードする／QuickDesign のアバターライブラリ（5,000+ のポートレート）から選ぶ／文章で説明したクリエイターで進める（合成画像のように見えるリスクあり）。 ユーザーの説明が簡潔な場合は、「ライブラリから選ぶ」をおすすめします。
    • シーン／ロケーション画像 — ユーザーが「キッチンのシーン」「浴室の鏡越しの自撮り」「オフィスデスクからの主観映像」などを撮影する場合、実際の部屋の参考写真があるか尋ねます。提供された場合は @Image3 として渡します。

    Seedance R2V の呼び出しは、次のようになります。

    quickdesign video generate --provider seedance \
      --reference-image product.jpg \
      --reference-image avatar.jpg \
      --reference-image scene.jpg \
      --aspect-ratio 9:16 --duration 12 --resolution 1080p \
      -p '@Image2 in @Image3, holds @Image1 toward camera. She says: "..." No music score. No subtitles or on-screen text.' \
      -o seg1.mp4 --wait
    

    @Image1／@Image2／@Image3 のラベルが重要な役割を果たします。文章では動作と引用するセリフのみを説明します。references/multi-reference-pattern.md を参照してください。

判断ツリー — 最初に開くドキュメント

作業の種類別：

リクエスト	まず読むファイル
UGC／トーキングアバター／プロモーション／解説動画／複数セグメントの広告	pipelines/ugc-video.md → models/seedance-2.0-r2v.md
画像編集（アングル、状態、複数製品の構図）	models/nano-banana-2.md → references/multi-reference-pattern.md
映像美重視の単一ショット（音声品質重視、4/8/12s）	models/sora2-i2v.md（ユーザーが明示的にオプトインした場合のみ）
低予算のループ動画／セリフなしの B ロール	models/kling-3-pro.md
最終動画の解像度が低すぎる	models/topaz-video-upscale.md（結合後に実行）
既存の動画に字幕を追加する	references/auto-subtitle.md
Spy Brands ライブラリにブランドがない／検索結果が 0 件	references/spybrands-add-on-miss.md
ユーザーが claude.ai（ウェブ）を利用していて、QuickDesign について質問している	references/connecting-claude-ai-via-mcp.md
デザインを広告として Meta に公開する／自社の Meta 広告のパフォーマンスを分析する	references/deploy-meta.md

作業フェーズ別：

フェーズ	読むもの
計画：スクリプト／尺の計算、ストーリー上の要点	references/script-and-duration.md、references/narrative-arc.md
事前確認：レジストリで利用可能なモデル	quickdesign video models、quickdesign cost --category video
セグメントごとの参照画像の選択	references/multi-reference-pattern.md、references/narrative-arc.md
生成：選択したモデルのプロンプトのひな型と注意点	models/<slug>.md
品質チェック：バナナの解剖学的な確認、計画の要約の承認	references/confirmation-rules.md
後処理：字幕、アップスケール	references/auto-subtitle.md、models/topaz-video-upscale.md

実行時に確認する

モデルレジストリはデータベース主導で、時間とともに変化します（新しいプロバイダー、廃止されたバージョン、価格改定されたティアなど）。モデルに関する前提をハードコードせず、選択肢を比較するときは、まずレジストリを確認してください。

quickdesign video models                            # active video models
quickdesign image models                            # active image-edit models
quickdesign cost                                    # all models, grouped by category
quickdesign cost --category video
quickdesign cost <slug> -d <duration> -r <resolution>   # exact compute for one model + params

現在のデフォルトより適した新しいモデルが登場したら、models/<slug>.md に新しいファイルを追加し（既存のカードの形式をコピー）、そのモデルが新たな共通デフォルトになった場合は、基本ルール #0 と判断ツリーを更新します。

クイックスタート — よく使うコマンド

# Auth (one-time, browser flow)
quickdesign auth login

# Image edit — angle change / state change / multi-ref product composition
quickdesign image generate \
  --model nano-banana-2 \
  --reference-image ~/path/to/avatar.jpg \
  --reference-image ~/path/to/product.jpg \
  --aspect-ratio 9:16 --resolution 2K \
  -p "@Image1 holds a product matching @Image2 exactly. ..." \
  -o ~/output.png --wait

# Single Seedance R2V (≤15s spoken script — still R2V, not i2v)
quickdesign video generate \
  --provider seedance \
  --reference-image ~/path/to/source.png \
  --aspect-ratio 9:16 --duration 12 --resolution 1080p \
  -o ~/output.mp4 --wait \
  -p '@Image1 in the same setting. <action>. He/She says: "..." No music score. No subtitles or on-screen text. Vertical 9:16 format.'

# Multi-segment Seedance R2V with voice continuity
# 1) Generate Seg 1 (sequential, native audio)
quickdesign video generate --provider seedance --reference-image seg1.png \
  --duration 12 --aspect-ratio 9:16 --resolution 1080p \
  -p '...' -o seg1.mp4 --wait
# 2) Extract Seg 1 audio
ffmpeg -y -i seg1.mp4 -vn -acodec libmp3lame -q:a 2 seg1-audio.mp3
# 3) Segs 2..N in parallel, each with --reference-audio
quickdesign video generate --provider seedance \
  --reference-image seg2.png --reference-audio seg1-audio.mp3 \
  --duration 12 --aspect-ratio 9:16 --resolution 1080p \
  -p '...' -o seg2.mp4 --wait &
# 4) Concat (mux-only, no quality loss)
printf "file 'seg1.mp4'\nfile 'seg2.mp4'\n" > /tmp/concat.txt
ffmpeg -y -f concat -safe 0 -i /tmp/concat.txt -c copy final.mp4

# Auto-subtitle (karaoke style, post-generation)
quickdesign video subtitle ./final.mp4 \
  --style tiktok --language en \
  -o ./final-subbed.mp4 --wait

ファイル一覧

SKILL.md                           ← you are here: cardinal rules + decision tree + nav
references/                        ← model-agnostic concepts (read for principles)
   confirmation-rules.md           ← gates, AskUserQuestion convention, anatomy self-check
   multi-reference-pattern.md      ← @Image1/@Image2/@Image3 multi-ref usage
   avatar-edit-not-regenerate.md   ← edit-style verbs, don't compose-regen the avatar
   spybrands-add-on-miss.md        ← when `spy brands --search` returns 0: confirm + resolve FB page + `spy add`
   connecting-claude-ai-via-mcp.md ← claude.ai (web) users: how to connect via MCP, what's available vs. CLI-only
   deploy-meta.md                  ← `meta` commands: publish designs as PAUSED Meta ads + insights/report/radar analytics
   voice-continuity.md             ← --reference-audio across multi-segment
   no-music-no-subtitles.md        ← minimal music + subtitle suppression
   auto-subtitle.md                ← post-generation captions (real ASR, not model-burned)
   narrative-arc.md                ← per-segment reference decision tree
   script-and-duration.md          ← word count → segment math, gender-neutral defaults
   first-frame-not-camera-motion.md ← why "static hold" / "slowly zooms" cause defects
   brand-and-moderation.md         ← brand-kit conventions, content moderation
pipelines/                         ← multi-step workflows (model-agnostic where possible)
   ugc-video.md                    ← canonical multi-segment talking-avatar method
models/                            ← per-model reference cards (gotchas + prompt skeletons)
   seedance-2.0-r2v.md             ← DEFAULT for UGC / promo / talking-avatar
   seedance-2.0-i2v.md             ← niche; explicit user opt-in only
   nano-banana-2.md                ← default for image edit + multi-ref product composition
   sora2-i2v.md                    ← cinematic single-shot, opt-in
   kling-3-pro.md                  ← budget alternative for non-spoken b-roll
   topaz-video-upscale.md          ← post-pipeline upscale

ユーザーから具体的な依頼があった場合は、models/ または pipelines/ 内の該当ファイルを直接開いてください。上記の基本ルールだけは、常にアクティブなコンテキストに含めておきます。