promo-video
從原始影片片段組裝短版宣傳影片。支援直式、正方形或橫式。可選用 Blender 渲染的片頭/片尾，以及可選的 AI 生成音樂。
此技能與主機代理無關：它在每個實作 Agent Skills 標準 (https://agentskills.io) 的執行環境中必須運作一致 —— Claude、Claude Code、OpenAI Codex、Gemini CLI、Cursor、GitHub Copilot、Cline、OpenCode、OpenHands、Goose、Kiro、Junie 及其他。切勿依賴主機專屬工具（除非明確可用，否則不使用 AskUserQuestion、斜線命令或 MCP）。所有使用者互動均以一般聊天訊息進行。
使用時機
- 「將這些片段剪接成一段 30 秒的短片。」
- 「幫我做一支直式的黑客松宣傳影片。」
- 「我有一個手機影片的資料夾 —— 製作一段 1080x1920 的社群影片加上音樂。」
- 「製作一支有 Logo 片頭 + 愛心片尾 + 背景音樂的宣傳片。」
- 使用者提及一個包含
.mov/.mp4檔案的目錄，並期望得到一個完整的輸出檔案。
前置需求
- 在 PATH 環境變數中可用的
ffmpeg，需編譯支援libx264、aac和prores_ks（最後一個僅在需要 Alpha 色版片頭/片尾 MOV 時需要）。 - Python 3.9+。
- 一次性安裝 Python 依賴：在技能目錄內執行
pip install -r requirements.txt。 - 可選：在專案根目錄放置包含
SUNO_API_KEY的.env檔案，以啟用音樂生成功能。技能會自動偵測是否設定此金鑰，並僅在已設定時提供音樂生成選項。 - 可選：在主機代理中設定 Blender MCP，以製作片頭/片尾渲染。請參閱
references/blender_mcp.md。
預設流程（對話式）
步驟 0 — 偵測片段自上次執行後是否變更
在詢問任何問題之前，先檢查使用者是否從先前的對話繼續。如果 gallery/.clips_snapshot.json 存在（或者使用者指向之前用過的片段資料夾），則執行：
python scripts/clip_diff.py <clips_dir>
- 退出碼 0 — 片段資料夾與最後的快照相符。繼續。
- 退出碼 1 — 有變動。報告會列出新增/移除/修改的片段。向使用者顯示，然後提議重新執行
scripts/gallery.py，以便圖庫更新片段。仍存在的片段的現有選取內容會保留不變。 - 退出碼 2 — 尚無快照。正常首次執行，繼續。
在繼續現有專案時，請勿跳過此步驟 —— 在未察覺的情況下對著過期圖庫/selection.json 工作，正是經典的「我的新片段跑去哪了？」錯誤來源。
問題
開始時，依序詢問使用者以下問題。接受自然語言回答；除非主機支援，否則不要使用多重選項 UI。對於每個問題，也接受「你決定」並套用合理的預設值。
- 目標格式。 1080x1920 直式（預設）、1920x1080 橫式、或 1080x1080 正方形。允許自訂尺寸。
- 片段來源。 包含原始片段目錄的絕對或相對路徑。支援
.mov、.mp4、.m4v格式。 - 目標長度（秒）。（典型值：20–45 秒）
- 音樂。 選項之一：(a) 現有音訊檔案、(b) 透過 Suno 生成（僅在設定
SUNO_API_KEY時提供）、(c) 無音樂。 - 片頭。 選項之一：無、靜態圖片（路徑）、Blender MCP 生成。
- 片尾。 與片頭相同的選項。
- 導演模式。 是或否。如果是，請遵循
references/director_mode.md，而非繼續線性進行。
然後處理片段選擇。提供兩種途徑：
A) 視覺圖庫（當片段超過 10 個或使用者希望在選擇提示之前看到影格時，建議使用）。 執行 scripts/gallery.py <clips_dir> --resolution WxH --fps 30 --target-length N —— 它會生成包含縮圖、IN/OUT 滑桿、速度滑桿和範圍預覽的 gallery/gallery.html。告知使用者在瀏覽器中開啟，挑選片段、設定提示，然後點擊「匯出 selection.json」。下載的檔案即可供 build.py 使用。
B) 內嵌對話（適用於少量片段或無法使用瀏覽器時）。 自行逐步處理每個片段：
cue_in和cue_out（秒，修剪範圍）speed倍率（1.0 = 原始速度）fixed: true如果時間/速度是人工挑選的，false則為自由填充項目（預設：從中間取 0.6 秒，速度 1.0）
提供「直接使用預設值」選項 —— 按字母順序選取每個片段、使用自由預設值、填滿至目標長度。
不論採用何種方式，結果都是符合 templates/selection.schema.json 的 selection.json。請在繼續前進行驗證。
建置
一旦 selection.json 驗證通過，執行：
python <skill>/scripts/build.py <selection.json> --out output/<name>.mp4
build.py 會在建置目錄（相對於目前工作目錄）下寫入中間產物：build/normalized/、build/trimmed/、build/montage.mp4、build/composed.mp4。刪除 build/ 目錄可強制完整重新渲染。
scripts/ 下的每個子模組也可獨立執行 —— 適用於迭代單一步驟而無需重建整個管線。每個模組都支援 --help 參數。
導演模式（選用）
選擇加入。請參閱 references/director_mode.md 的角色提示。此技能會產生四個依序執行的角色 —— 敘述者 → 剪輯師 → 作曲家 → 監督者 —— 它們共享 selection.json 作為狀態。每個角色讀取目前的 JSON 並將其更新寫回。當使用者要求「更有引導性的流程」或「像製作人一樣帶領我」時，請使用此模式。
音樂生成（選用）
如果使用者選擇「透過 Suno 生成」，請將音樂步驟委派給 references/song_builder_agent.md 中定義的 Song-Builder 子代理。該子代理：
- 詢問使用者風格、情緒、BPM 範圍、段落結構、是否純音樂，並將影片長度作為持續時間。
- 制定 Suno 提示和樣式標籤。
- 呼叫
scripts/music.generate_song(spec)—— 如果使用者想比較選項，請提供takes > 1。 - 將選定的錄製修剪並淡入淡出至影片長度。
- 將最終的 mp3 路徑寫入
selection.json作為audio。
如果主機提供子代理機制（例如 Claude Code 的 Agent 工具），請使用它。否則，請在同一執行緒內以內嵌方式扮演該角色。
Blender MCP 整合（選用）
僅提供協助 —— 此技能不包含 Blender 場景。
如果使用者希望使用 Blender 渲染的片頭或片尾，請將任務委派給 references/blender_builder_agent.md 中定義的 Blender-Builder 子代理。它負責整個流程：前置檢查（確認此主機上 Blender + MCP 確實可連線）、設計訪談（視覺方向、顏色、持續時間）、場景建置、迭代預覽、渲染為 ProRes 4444 Alpha MOV，並將 MOV 路徑移交至 selection.json。
如果主機提供子代理機制（例如 Claude Code 的 Agent 工具），請啟動它。否則，請以內嵌方式扮演該角色。當使用者在問卷步驟 5 中為片頭或片尾選擇「Blender MCP 生成」時，主要對話流程應呼叫 Blender-Builder。
設定文件（安裝 Blender、安裝 MCP 伺服器、向主機註冊）位於 references/blender_mcp.md。當使用者需要首次設定堆疊時，Blender-Builder 子代理會參考該文件。
錯誤復原
- 如果某個片段正規化失敗（編碼器/解析度邊界案例），
build.py會以非零退出碼和明確的標準錯誤訊息退出，指出問題檔案。詢問使用者是要跳過該片段還是進行調查。 - 如果 Suno 回傳 4xx 狀態碼或逾時，請提供使用者重試、切換至「現有檔案」、或無音樂繼續進行的選項。
- 絕不悄無聲息地遺失片段。除非傳遞
--force參數，否則絕不覆蓋現有輸出檔案而不經確認。
此技能的風格注意事項
- 絕不假設主機專屬工具。 所有對話均為純文字聊天。
- 展示你的工作。 修剪時，在建置前告知使用者你最終確定的提示點。
- 大聲失敗。 如果缺少
ffmpeg，請明確指出並顯示適用於該使用者平台的安裝指令。