Storyboard Architect
你正在將一個創意簡報轉化為確定性的故事板。輸出是一組檔案,編輯、代理商或開發者可以直接據以行動,無需提出後續問題。
這不是創意寫作練習。輸出是一份規格書。
使用時機
當使用者有下列情況時,觸發此技能:
- 要求為某支影片製作故事板或分鏡清單(例如:「為一個30秒解說影片製作故事板……」、「為一個TikTok廣告製作分鏡清單……」)
- 要求規劃鏡頭、分解節拍或撰寫分鏡清單
- 提供腳本、簡報或概念文件,並期望獲得結構化的前期製作輸出
- 提及特定的節奏框架(如 Hero Trilogy、Pain-Proof-Promise 等)
- 參考現有的品牌鎖定檔案或套件
如果使用者只需要圖片生成提示(無敘事結構),請改為直接使用 visual-prompt-forge。
你會產出什麼
每次故事板執行,在工作的輸出目錄中建立這組精確的檔案:
output/
├── run.json # 執行身分 + 每個輸入的內容雜湊
├── storyboard.md # 人類可讀,結構化每個鏡頭
├── shots.json # 機器可讀,結構定義在 templates/shots.schema.json
├── text-overlays.json # 螢幕文字 + 時間碼
└── brand-lock.snapshot.md # 所使用的品牌鎖定凍結副本(稽核軌跡)
run.json 是讓整個檔案樹日後可被稽核的關鍵。檔名本身無法保證其位元組內容,因此放在一組畫面旁的快照並不能證明它們是據以建立的原始快照。run.json 中的雜湊就是那個證明。在其它四個檔案都確定後,最後一步才寫入 run.json。run.json 中的所有內容(除了 rounds)都是一次寫入、永不編輯的。rounds 是僅追加的:visual-prompt-forge 每次提示回合會新增一個條目,且絕不更改先前的條目。
如果使用者要求圖片提示或 HTML 預覽,請交由 visual-prompt-forge 或 storyboard-html-preview 處理,這些技能會直接讀取 shots.json。不要在這裡越俎代庖。
工具與品牌套件的位置
執行 ./install.sh 後,驗證工具與輔助工具位於 ~/.claude/shotkit-tools/,品牌套件位於 ~/.claude/shotkit-brand-packs/。使用 --project 安裝則兩者會放在 ./.claude/ 下。從儲存庫複製時,它們是 tools/ 和 brand-packs/。下方指令會先給出安裝後的路徑,再給出複製後的路徑。它們無需設定:sk 會執行每個工具,並提供驗證工具所需的兩個 Python 套件。
輸入
你需要以下項目。如果任何一項缺失,請在起草前先詢問。
| 輸入 | 必要? | 若無則預設值 |
|---|---|---|
| 簡報(問題、受眾、目標) | 是 | 詢問 |
| 總時長 | 是 | 詢問 |
| 畫面比例 | 是 | 詢問(16:9、9:16、1:1) |
| 節奏框架 | 否 | 根據簡報建議 |
| 品牌鎖定檔案路徑 | 否 | 使用 ~/.claude/shotkit-brand-packs/_starter.md(複製:brand-packs/_starter.md)並標註缺口 |
| 旁白風格(有旁白、僅螢幕文字、字幕) | 否 | 若不清楚則詢問 |
| 下游提示的目標生成器 | 否 | 標註為「待指定」 |
稽核結果(來自 whystrohm-audit 的 brand/audit-findings.json) | 否 | 跳過步驟 1b |
閱讀預算
此檔案涵蓋一般執行所需內容:欄位、詞彙表和檔案格式。請勿預先閱讀參考資料、範本和範例。那樣做會在使用者看到第一個檔案前浪費數分鐘。
- 務必閱讀:品牌鎖定。
- 當決策需要時閱讀:
references/beat-frameworks.md(針對不熟悉的框架)、references/timing-rules.md(當簡報與長度不一致時)、references/on-screen-text.md(當不確定一行文字是否應在螢幕上時)。 - 當驗證工具要求時閱讀:
templates/中的結構定義。其訊息會指出欄位和規則,因此先根據訊息修正。 - 最後(如果有的話)才閱讀:範例。
工作流程
依序執行以下步驟。即使簡報看起來很簡單,也不要跳過任何步驟。
步驟 1. 讀取品牌鎖定
如果提供了品牌鎖定檔案路徑,請先讀取它。提取:
- 色板(十六進位)
- 字體排版
- 情緒描述詞
- 「永不」清單(該品牌永遠不會在視覺上做的事)
- 動態語言
- 語氣
- 畫面比例偏好
如果未提供品牌鎖定,請將 ~/.claude/shotkit-brand-packs/_starter.md(從複製:brand-packs/_starter.md)複製到輸出目錄,命名為 brand-lock.snapshot.md。起手式是一個中立、已填寫的鎖定,因此快照能通過檢查,並且重疊元素有真實的顏色可用。在 run.json 中設定 brand_lock_configured: false,並告知使用者此次執行使用了起手品牌以及如何替換:要求使用者從其網站提供品牌鎖定,或填寫 _template.md。
請勿快照 _template.md。它刻意保持空白,空白的色板會導致快照檢查失敗。也不要為真實公司憑空發明色板:一個憑空發明的品牌鎖定,看起來像是公司做出的決定。
步驟 1b. 讀取稽核結果(如果有的話)
如果使用者指向 brand/audit-findings.json,或者它位於專案的 brand/ 資料夾中且簡報是針對同一家公司,請讀取它。其格式為此儲存庫中的 contracts/audit-findings.v1.schema.json。在使用前,請檢查 contract 是否為 audit-findings 且 version 是否為 "1"。
top_gaps中的第一個項目是痛苦或世界節拍的候選:即影片要解答的問題。rewrite.after是候選的重疊文字行。僅按原樣使用。如果其中包含括號佔位符,表示證據缺失,請跳過該行而非自行填寫。- 在
storyboard.md的「簡報」區段中提及該檔案名稱及其audited_at。
最終仍由簡報決定。稽核結果可以為節拍提供資訊,但絕不能取代使用者要求的內容。
步驟 2. 選擇節奏框架
閱讀 references/beat-frameworks.md。選擇與簡報相符的框架。常見案例:
- Pain-reframe-promise → 轉換型內容
- Hero Trilogy → 產品英雄影片
- Founder Explainer → 個人品牌內容
- Content Spiral → 動態字體排版 / 評論文章
如果沒有完全符合的,建立自訂節奏結構,但需在 storyboard.md 的「理由」區段中說明原因。
步驟 3. 劃分時間
閱讀 references/timing-rules.md 以了解計算方式。預設節奏:
- 鉤子節拍:0–2 秒
- 痛苦/鋪陳:2–4 秒(15秒)、2–6 秒(30秒)或 2–10 秒(60秒)
- 證明/重新框架:中間三分之一
- 承諾/CTA:最後 3–4 秒(15秒)、4–6 秒(30秒)、6–10 秒(60秒)
不要與框架對抗。如果簡報和時長不一致,請在起草前先指出這個矛盾。
步驟 4. 起草分鏡清單
閱讀 references/shot-grammar.md 以了解受控詞彙。下列欄位名稱是結構定義的欄位名稱。templates/shots.schema.json 設定了 additionalProperties: false,因此像是 environment 而非 environment_ref 這種近似錯誤是驗證失敗,而非同義詞。
id,依序,零填充(shot_01、shot_02……)beat,此鏡頭服務的節拍start/end,時間戳記(秒,允許小數)。end必須在start之後framing,ECU / CU / MCU / MS / MLS / WS / EWSangle,eye-level / high / low / overhead / dutchmotion,static / push / pull / pan-left / pan-right / tilt-up / tilt-down / handheld / orbit / whip / rack。全部十一個都是合法的;結構定義的枚舉是權威,references/shot-grammar.md則說明每個詞彙何時發揮作用depth_of_field,可選,shallow / deep / racksubject,畫面中的主體,結構化environment_ref,參考系列鎖定語言,預設為series_lock.environmentlighting_ref,參考系列鎖定語言,預設為series_lock.lightingon_screen_text,null、一個文字重疊 ID,或一個 ID 陣列(當一個鏡頭有多個重疊時)vo,旁白文字,或 nullrationale,一句話說明為什麼在此時用此鏡頭
關於 rack:作為 motion 值時,表示拉焦是鏡頭的運動;作為 depth_of_field 值時,表示焦點在鏡頭中轉移。同一個詞,兩個欄位,兩種意義。
步驟 5. 分離文字層
每個螢幕文字都成為 text-overlays.json 中的一個條目。切勿將文字寫死在視覺描述中。每個重疊元素有:
id,text_01、text_02……shot_id,此重疊疊加的鏡頭content,實際文字font,參考品牌鎖定字體排版position,center、lower-third、upper-third、left-third、right-third,或{x, y}百分比size,display、headline、body、captionweight,regular(400)、medium(500)、semibold(600)、bold(700)、black(900)color,十六進位(必須來自品牌鎖定色板)enter,{ at: seconds, animation: fade-in | slide-up | slide-down | type-on | hard-cut }exit,{ at: seconds, animation: fade-out | slide-up | slide-down | hard-cut }
然後設定類型並檢查文字:
- 類型處理。用
emphasis標記每個標題中承載重量的兩三個詞,用kicker或lockup提及品牌一次,並在畫面雜亂時使用plate。欄位及其使用時機詳見references/on-screen-text.md中的「類型處理」。 - 語言檢查。在寫入檔案前,將每行文字都經過
references/hooks-and-language.md檢查:第一行必須是鉤子而非口號,使用具體的詞,每行一個概念,不要使用簡報中沒有的內容。 - 沒有字體的品牌。從品牌套件資料夾的
type-pairings.md中選擇一組字體配對,並寫入品牌鎖定。不要預設使用 Inter。
進入和退出的動畫詞彙不同,templates/text-overlays.schema.json 是兩者的權威。一個鏡頭可能有多個重疊;將所有 ID 列在該鏡頭的 on_screen_text 陣列中,否則超出的重疊將不會被渲染。
步驟 6. 鎖定系列
定義適用於所有鏡頭的環境、燈光和角色錨點。這些放在 shots.json 頂部的 series_lock 下。沒有這些,圖片生成將產生不一致的畫面。
步驟 7. 撰寫理由
每個鏡頭都有一句理由。為什麼這個節拍。為什麼這個構圖。為什麼這個螢幕文字。這是稽核軌跡。不要跳過。
步驟 8. 快照品牌鎖定
將品牌鎖定檔案(或範本)複製到輸出目錄,命名為 brand-lock.snapshot.md。在最上方加入這兩行註解,順序如下:
<!-- snapshot taken: 2026-05-07T14:23:00Z -->
<!-- source: brand-packs/whystrohm.md -->
時間戳記是一個完整的 UTC 時刻,YYYY-MM-DDThh:mm:ssZ。只有日期無法區分同一天的兩次執行,而這正是重要的情況。來源是被複製的路徑,或是未設定執行時的 literal 字串 template default。安裝後,套件路徑為 ~/.claude/shotkit-brand-packs/whystrohm.md;從儲存庫複製時為 brand-packs/whystrohm.md。兩者都能通過驗證器。在這兩行之後加入額外的註解是可以的。
validate_brand_lock.py --snapshot <path> 會檢查這兩行。執行它:
~/.claude/shotkit-tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md
# from a repo clone:
# tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md
步驟 9. 撰寫 run.json
最後一步,在其餘四個檔案確定之後。填寫 templates/run.schema.json。這些欄位是必要的:
| 欄位 | 值 |
|---|---|
version | "1.0",run.json 的格式 |
run_id | 緊湊 UTC 時間戳記、一個連字號、8 個十六進位字元(如下) |
created_at | 與上相同的時刻,格式為 YYYY-MM-DDThh:mm:ssZ |
shotkit_version | ~/.claude/shotkit-tools/VERSION 的第一行;在儲存庫複製中,為根目錄的 VERSION |
project | 來自 shots.json 的 title、duration_s 和 aspect,以及 framework 和 seed(如有設定) |
inputs.shots_ref, inputs.shots_sha256 | shots.json 及其 SHA-256 |
inputs.text_overlays_ref, inputs.text_overlays_sha256 | text-overlays.json 及其 SHA-256,或如果沒有螢幕文字則兩者皆為 null |
inputs.brand_lock_ref, inputs.brand_lock_sha256 | brand-lock.snapshot.md 及其 SHA-256 |
inputs.brand_lock_source | 複製來源的套件,或 template default |
可選:operator、inputs.brand_lock_configured、generators、rounds、meta。
head -n 1 ~/.claude/shotkit-tools/VERSION # from a repo clone: head -n 1 VERSION
shasum -a 256 output/shots.json output/text-overlays.json output/brand-lock.snapshot.md
run_id 是緊湊 UTC 時間戳記、一個連字號、8 個十六進位字元,例如 20260730T142300Z-9f2c1ab4。十六進位後綴用於防止兩個操作者在同一秒開始執行時發生衝突。當快照是未填寫的範本時,設定 brand_lock_configured: false。
將 rounds 留空。run.json 中的所有內容(除了 rounds)都是一次寫入、永不編輯的。rounds 是僅追加的:visual-prompt-forge 每次提示回合會新增一個條目,且絕不更改先前的條目。
輸出格式
storyboard.md
每個區段一個標題,順序如下:提供的簡報、你做出的假設、框架及其原因、系列鎖定,然後是每個鏡頭一個區塊(id、節拍、時間、攝影機、主體、螢幕文字、旁白、理由),最後是完整的旁白腳本(如果有的話)。templates/storyboard.md.tpl 有精確的版面配置(如果需要參考)。
shots.json
必須通過 templates/shots.schema.json 的驗證。結構如下:
{
"version": "1.2",
"project": { "title": "...", "duration_s": 30, "aspect": "9:16", "framework": "..." },
"brand_lock_ref": "brand-lock.snapshot.md",
"series_lock": {
"character": "...",
"environment": "...",
"lighting": "...",
"color_grade": "..."
},
"shots": [
{
"id": "shot_01",
"beat": "hook",
"start": 0.0,
"end": 2.0,
"framing": "MCU",
"angle": "eye-level",
"motion": "static",
"depth_of_field": "shallow",
"subject": "...",
"environment_ref": "...",
"lighting_ref": "...",
"on_screen_text": null,
"vo": "...",
"rationale": "..."
}
]
}
text-overlays.json
必須通過 templates/text-overlays.schema.json 的驗證。
brand-lock.snapshot.md
品牌鎖定檔案的凍結副本,頂部加上兩行註解。
run.json
必須通過 templates/run.schema.json 的驗證。
驗證
撰寫 shots.json 和 text-overlays.json 後,使用驗證工具:
~/.claude/shotkit-tools/sk validate_shots.py output/shots.json
~/.claude/shotkit-tools/sk validate_text_overlays.py output/text-overlays.json
~/.claude/shotkit-tools/sk validate_run.py output/run.json
從儲存庫複製時:
tools/sk validate_shots.py output/shots.json
tools/sk validate_text_overlays.py output/text-overlays.json
tools/sk validate_run.py output/run.json
sk 是 shotkit-tools 的入口點腳本。它設定 PYTHONPATH 以包含驗證工具所需的兩個套件(在 lib/ 下)。除非你正在除錯 sk 本身,否則請使用 sk 而非直接呼叫 Python。
品牌鎖定快照驗證
~/.claude/shotkit-tools/sk validate_brand_lock.py --snapshot output/brand-lock.snapshot.md
這會檢查頂部的兩行註解是否存在,以及時間戳記是否為有效的 UTC 格式。