Communitygithub.com

說明影片製作 (Hellboy)

將一個技術主題,轉化為 2-3 分鐘、直式 (9:16) 的 MP4 說明影片,專為非技術背景的觀眾設計,並以卡通建築師「Hellboy」作為角色呈現。

說明影片製作 (Hellboy) 是什麼?

這項技能能將單一技術主題,從腳本構思到最終影片渲染,完整自動化。它會產出一個文字腳本 (script.md) 和一個結構化的故事板 (storyboard.json),然後交由後端的渲染引擎處理配音、字幕、動畫、角色和音樂。影片風格與節奏是從一個參考頻道複製而來,但角色 (Hellboy) 和聲音是固定的。此技能支援 Claude Code、Cursor、Codex 等平台,並提供一個專為較小模型設計的「小模型操作手冊」,能將工作拆解為逐個場景的提示,避免一次性處理大量資料。透過遵循嚴格的 7 拍腳本結構、場景視覺類型決策表,以及長度與字數限制,確保內容對非技術觀眾而言既簡單又吸引人。驗證器會強制執行所有規則,並在渲染前確保零錯誤,最後產出 1080×1920 解析度的 MP4 檔案。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/bhuvanchandmaddi/video-generator-skill/tree/HEAD/skills/explainer-video

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

說明影片製作技能 (Hellboy)

你將一個技術主題轉變為一部完成的 2–3 分鐘 1080×1920 MP4 影片,讓非技術背景的人在第一次觀看時就能理解。視覺風格、節奏和腳本結構皆從一個參考頻道複製而來(於 docs/01-style-bible.md 中分析)。有兩樣東西是我們刻意保有的:角色 (Hellboy) 和聲音。

你只需撰寫純文字檔案(一份腳本和一個 storyboard.json)。engine/ 中的引擎會處理聲音、字幕、動畫、角色、音樂和渲染。


當使用者只提供一個主題時

請直接完成整個工作,無需提出額外問題:

  1. 根據主題建立一個 slug(例如 how-dns-works),並執行 python engine/make_video.py new videos/<slug>。
  2. 撰寫 videos/<slug>/script.md(請參考 docs/02),接著撰寫 videos/<slug>/storyboard.json(請參考 docs/03 + docs/04)。從 examples/upi-explained/ 中複製模式。
  3. 執行 python engine/validate_storyboard.py videos/<slug>。修正所有 ERROR,並重複此步驟,直到顯示 0 error(s) 為止。
  4. 執行 python engine/make_video.py preview videos/<slug>。如果你能看到圖片,請比對 build/preview.png 與 docs/06 的 B 節,並進行修正。
  5. 執行 python engine/make_video.py render videos/<slug>。回覆時請包含路徑 output/<slug>.mp4、影片長度以及兩行摘要。

不可妥協的原則

  1. Hellboy 絕不能重繪。 他只能從 character/hellboy/hellboy.js 中取得。你只能設定 show、arm(down/point/explain)和 expression,除此之外都不行。請將 character/hellboy/CHARACTER_BIBLE.md 閱讀一次。
  2. 聲音是固定的,定義在 engine/config.json 中。請勿為單支影片更改。
  3. 長度:旁白 360–470 字,時間 2:00–2:50。 每個句子不超過 20 個字。
  4. 每個句子都必須讓畫面產生變化。 項目應在其口語對應的關鍵字出現時顯示(使用 "at" 參數)。
  5. 正確比簡化更重要。 寧可省略也不要說錯。
  6. 驗證器必須通過(顯示 0 errors)才能進行渲染。

工作流程(請依序執行)

#步驟閱讀材料輸出結果
1建立骨架–python engine/make_video.py new videos/<slug>
2規劃並撰寫腳本docs/02-script-writing.mdvideos/<slug>/script.md(360–470 字,7 拍)
3規劃視覺docs/03-visual-planning.md場景列表:旁白 → 類型、標題、角色
4撰寫故事板docs/04-storyboard-reference.mdvideos/<slug>/storyboard.json(或 meta.json + scenes.jsonl → 使用 assemble 組合)
5驗證–python engine/validate_storyboard.py videos/<slug> → 修正直到 0 錯誤
6預覽 + 品質檢查docs/06-qa-checklist.mdmake_video.py preview videos/<slug> → 檢查 build/preview.png,修正問題
7渲染docs/05-production.mdmake_video.py render videos/<slug> → output/<slug>.mp4
8最終品質檢查docs/06-qa-checklist.md分數 ≥ 85,所有 MUST 項目必須通過

使用小型/本地模型? 請按照 docs/07-small-model-playbook.md 的步驟進行,以取代步驟 2–5。它將工作拆解為一次只處理一個場景的提示。

7 拍腳本結構(請記住)

鉤子(≤ 22 字:「X 解釋。」/ 「X 實際上如何運作?」/ 令人驚訝的宣稱 / relatable 的行為)→ 緊張(謎團)→ 路線圖(「讓我們跟著……」)→ 主體(3–6 章節:概念 → 平實的解釋 → 日常範例 → 後果;使用一個貫穿全場的範例,並有一個命名的人物)→ 轉折(「但有趣的地方是……」)→ 總結(「所以這樣記住。」每個章節一行)→ 金句(呼應鉤子的片段:「一次掃描。四個參與者。兩秒鐘。」)。

場景配方(請記住)

  • 1 個場景 = 1–3 個句子(8–28 字,3–8 秒);每支影片 20–32 個場景。
  • 根據 docs/03-visual-planning.md 中的決策表選擇 visual.type。每支影片使用 7–12 種不同的類型。
  • 在 40–70% 的場景中顯示 Hellboy(總是:第一個場景、轉折、總結、最後一個場景)。對於 sequence、hub、diagram、compare 類型則隱藏他。
  • 使用 "continue": true 搭配 "shown": true 的項目和相同的標題,在 2–4 個場景中逐步建立大型圖表。
  • 標題 2–6 個字,包含一個帶有 *accent* 標記的詞。螢幕上的標籤 1–4 個字。

指令(從儲存庫根目錄執行)

# 首先啟動虛擬環境:  source .venv/bin/activate   |   Windows: .\.venv\Scripts\Activate.ps1
python engine/make_video.py new       videos/<slug>   # 範本
python engine/make_video.py assemble  videos/<slug>   # meta.json + scenes.jsonl -> storyboard.json
python engine/validate_storyboard.py  videos/<slug>   # 必須為 0 錯誤
python engine/make_video.py preview   videos/<slug>   # build/preview.png(每個場景一幀)
python engine/make_video.py render    videos/<slug> [--fast]

首次在某台機器上使用時:./setup.sh(Linux/macOS)或 setup.ps1(Windows)。完成的影片會放置在 output/<slug>.mp4。

參考資料

  • examples/upi-explained/(暖紙風格)和 examples/load-balancer-explained/(藍圖風格)— 完整的實作範例。請複製它們的模式。
  • templates/ — script.template.md、storyboard.template.json。
  • docs/01-style-bible.md — 參考頻道做了什麼、如何測量(規則存在的原因)。
  • engine/icon_names.txt — 所有 2,359 個允許的圖示名稱(Lucide)。

相關技能