yamlreel-video-skills 是做什麼的？
編寫一份 YAML 規格，用 yamlreel 在本地端渲染，檢查聯絡頁面，然後將影片交給使用者。<skill> 指的是此檔案所在的目錄。
工作流程
- 設定。 執行
python3 <skill>/scripts/check_setup.py（它也會檢查 yamlreel 版本與功能）。若失敗，向使用者顯示列印的修正指示。僅在使用者同意後才執行--install。切勿自行安裝字型或系統套件。 - 釐清 在一則訊息中，提供預設值：主題、受眾、格式（預設直式）、長度（預設 30 秒）、主題（
midnight|sumi|washi）、語音（預設無）。跳過使用者已提及的內容。 - 先寫腳本。 以
references/writing-guide.md的節拍格式編寫videos/<slug>/script.txt（目標長度，每個節拍一個[BEAT - input -> action -> result]區塊，附上台詞，然後是交付備註）並展示給使用者。如果使用者要求先審查，請在獲得同意前停止，不要開始草稿或渲染。 大綱。 然後編寫videos/<slug>/outline.yaml（主題、鉤子、問題、1-6 個步驟，每個步驟包含name、say、show，再加上 when_to_use、question、answers）。規則在references/writing-guide.md：15 秒 = 一個想法；30-45 秒 = 一個想法加上最多 3 個步驟；#Shorts 最多 60 秒。 - 草稿：
yamlreel story videos/<slug>/outline.yaml --out videos/<slug>/spec.yaml --format <fmt> --theme <t>。僅對你自己建立的檔案使用--force。 - 編輯規格。 替換每個
TODO；設定meta.title/description/tags、formats、music.seed。螢幕上的文字要簡短；旁白解釋螢幕內容，且絕不重複。每個場景類型的欄位：references/scene-types.md。 - 預覽：
python3 <skill>/scripts/render.py videos/<slug>/spec.yaml --stage preview --out videos/<slug>/out。若遇錯誤，根據訊息修復規格（未知欄位錯誤會列出允許的鍵）及references/troubleshooting.md。最多重試 3 次，之後回報給使用者。 - 檢查（強制）。 使用圖片檢視工具開啟
RESULT行中列出的每個contact.png。檢查：無重疊、無裁剪或縮小的文字、靜止畫面能展現進度、第一個靜止畫面的鉤子可讀。修復規格並重複步驟 6，直到乾淨為止，最多 3 次循環。 - 最終：
python3 <skill>/scripts/render.py videos/<slug>/spec.yaml --stage final --out videos/<slug>/out。 - 選擇性潤色。 若使用者想要音效、音量修正或循環檢查，且
yamlreel audit --help可用，則對完成的video.mp4遵循references/polish.md（它絕不碰觸規格）。 - 回報 每個
video.mp4、poster.jpg和contact.png的路徑，並貼上share-copy.txt的內容。提醒使用者檢查任何被簡化的內容是否正確。發布是使用者的責任。
render.py 退出碼：0 成功，1 yamlreel 錯誤（stderr 會回顯），2 預檢拒絕（訊息會說明原因），3 預覽警告阻擋最終渲染（縮短文字，重新排列 at 提示；僅在使用者接受時使用 --allow-warnings），4 參數錯誤（例如 --contact-frames 超出 1-8 範圍）。
其最後一行是 RESULT {json}，包含每個輸出路徑。日誌會寫入 <out>/render-log.txt。
預設值與事實
- 渲染使用
--no-voice（僅音樂）。在無語音渲染中看不到字幕和旁白；這是預期行為。 - 輸出位於
<out>/{preview,final}/<format>/；務必使用--out videos/<slug>/out，讓兩個專案不會共用同一資料夾（預設為<spec 資料夾>/out）。 - 固定的
music.seed可確保渲染結果一致性。除非使用者要求，否則不要加入watermark。 - 旁白為選用，需自行提供：請參閱
references/voiceover.md。 - 可參考的範例：
examples/*.yaml。
安全規則
- 切勿將機密資訊、令牌、
.env內容、內部主機名稱或個人/客戶資料放入規格中：這些內容會被燒錄到影格及share-copy.txt。程式碼範例請使用佔位符。 - 僅在使用者的專案資料夾內讀寫；將圖片放在規格旁。除非使用者明確要求並指定資料夾名稱，否則不要加入
--allow-path或--allow-private-hosts。 - 僅能使用使用者指定的本機 TTS 伺服器進行語音；旁白文字會傳送給它。絕不使用遠端 URL。
- 未經使用者同意，切勿安裝系統套件或字型，或編輯
~/.config/yamlreel/config.yaml。 shot場景：僅限使用者提供的公開 https URL，或專案內的本地圖片。- 切勿上傳或發布結果。