剪輯（Cut）
路徑：${CLAUDE_SKILL_DIR} 代表包含此 SKILL.md 的資料夾，${CLAUDE_SKILL_DIR}/../.. 代表編輯器資料夾（此 repo 的 .claude/），位於上方兩層。
請先閱讀 ${CLAUDE_SKILL_DIR}/../../PRINCIPLES.md：裡面是所有影片都必須遵守的規則。
所有問題都放在問題框中：使用 AskUserQuestion 工具（2-4 個選項，建議第一個）。只有在沒有該工具的 agent 中，才以文字列出編號問題。
edits/<name>/ transcript.txt（請讀這個，不要讀 words.raw.json），spans.json（要移除的內容，加引號），
candidates.md（程式碼標記的候選項目），paper-edit.md（以文字呈現的剪輯），cut-check.html（
逐字稿），review.json（備註），cut.mp4 + words.json（渲染結果及其文字）。
<name> 是檔案名稱的 slug（IMG_1234.MOV → img-1234），放在資料庫中（PRINCIPLES.md 的「Where」）。請勿修改、移動或複製原始檔案：傳遞其路徑即可。
PY="${CLAUDE_SKILL_DIR}/../../lib/ai_editor/run.py"；使用 python3 "$PY" 來執行工具 venv。在 Windows 上，請使用 py 代替以下命令中的 python3。
還沒有 venv：請先執行 setup 技能。S="${CLAUDE_SKILL_DIR}/scripts"。
還沒有影片？
詢問他們素材的路徑。多個檔案：references/takes.md。沒有檔案：當 AI_EDITOR_SAMPLE_URL 已設定時，提供該範例素材並下載到他們的資料夾（curl -L -o sample-take.mp4 "$AI_EDITOR_SAMPLE_URL"）；否則請他們錄製一段（任何手機拍攝的 30-60 秒 talking-head 影片皆可）。
0. 詢問：先剪輯，還是一次到位
在開始任何步驟前，先在問題框中問一個問題（start 技能會為完整編輯決定此問題）：
您想先看剪輯結果，還是剪輯與風格編輯一次完成？
- 先看剪輯結果（建議）。 您先核准剪輯，我再加入字幕、縮放或視覺效果，這樣變更剪輯時就不需重做視覺效果（節省 tokens）。
- 一次到位。 我剪輯完直接套用風格，不等待。您仍會看到剪輯頁面與靜態圖表，然後才開始渲染。
只有當使用者已回答（「直接剪掉」、「一次完成剪輯與風格」）或由 start 或 clips 呼叫此技能時，才跳過此步驟。先看剪輯結果： 步驟 1-6，然後停止，直到使用者核准剪輯 並且 要求套用風格。一次到位： 步驟 1-5，開啟剪輯頁面，直接繼續進行 style-edit；之後若變更剪輯，會從 style-edit 的規劃步驟重新執行。
0b. 讀取使用者偏好
python3 "${CLAUDE_SKILL_DIR}/../../skills/taste/scripts/taste.py" show --edit edits/<name>
遵守其中的每一條規則。在重做之前，使用 taste 技能儲存對結果的反應（例如「太慢」）。
1. 轉錄
python3 "$PY" "$S/transcribe.py" <source> edits/<name>/words.raw.json [--script <their script>]
提供腳本（或可重複使用的 --keyterm Name）可以讓名稱與術語更準確（Scribe 提升 20%）。
先告知時間：Whisper 對 3 分鐘素材需要 1-4 分鐘，CrisperWhisper 約等於素材長度。如果已儲存金鑰，則選用 Scribe；否則選用已安裝的 CrisperWhisper；再不然就是用免費的本機 Whisper（可透過 --engine whisper|crisper|scribe 覆蓋），後者會漏掉一些「嗯」和假開頭。如果兩者都沒有，請事先告知可透過 setup 技能安裝其中一個（CrisperWhisper 的權重僅供非商業用途）。請勿在編輯中途下載模型：如果檢查發現需要但未安裝（exit 4），則跳過該步驟並在該輪的備註中說明。
切勿讀取 words.raw.json：步驟 2 會寫入 transcript.txt，大小僅為其 1/12。
2. 決定要剪哪些
python3 "$S/retakes.py" propose edits/<name>
程式碼會找出所有可能的剪輯點（重複的句子、未完成的句子、「等一下、抱歉」、填充詞）並寫入 candidates.md。每個候選項目只是一個參考點，而非最終決定。請閱讀 transcript.txt 和 candidates.md，遵循 references/retake-detection.md，然後寫入 spans.json（參閱 references/shapes.md）。
若有 script.md：執行 python3 "$S/script_match.py" edits/<name>，然後閱讀 script-match.md（參閱 references/script.md）。
最後一次拍攝為準，但「替換鉤子」除外。請勿手動輸入時間戳或為停頓設定範圍。
只有當使用者希望影片更短（或偏好檔案中要求執行編輯校對）時，才需閱讀 references/editorial-rules.md，並加入 redundant 剪輯（由內容觸發）。
若名稱聽錯，只需一條命令，無需手動修改 JSON：python3 "$S/retakes.py" fix edits/<name> cloud=Claude jiv=Jev（整詞保留，會寫入 fixes.json 供字幕使用）。
3. 建置
python3 "$S/build_timeline.py" <source> edits/<name> && python3 "$PY" "$S/mirror.py" <source> edits/<name>
所有超過 --max-pause（0.15 秒）的停頓（包括呼吸聲）都會被縮短為 0.10 秒；在只有音樂的情況下，只會修剪單字間的空隙。如果建置出現 ERROR，則不產生任何輸出：修正該時間範圍後重新執行。
mirror.py 會提示 mirrored，代表出現書籍、襯衫或標誌顯示相反的情況（前置鏡頭拍攝）：請詢問一次，維持原樣（建議）（多數創作者直接發布）／翻轉使文字可讀；若翻轉，請在後續每個 render.py 命令中加入 --flip。
在單一訊息中，同時在背景啟動 spans 編碼（run_in_background）與 paper 檢查；步驟 4 只會重新編碼已變更的部分：
python3 "$S/render.py" <source> edits/<name> --segments-only
cut-judge agent 會為 paper-edit.md 評分（遺漏的失誤、不良銜接、遺失的好句子），並修正 spans.json。對於超過 5 分鐘的素材，先執行 reader，再執行 judge：請參閱 references/judge.md。請勿自行閱讀 paper-edit.md。
- 如果
paper-edit.md出現CLIPPED：表示停頓剪輯吃掉了一個字。請提高--pad。若仍存在：表示標籤偏移。 - 語音內部的銜接應移至安靜的影格。任何
still in speech：請在步驟 5 中聆聽。
4-5. 渲染與驗證
前景執行（render.py 會等待背景編碼完成）：
R="${CLAUDE_SKILL_DIR}/../../lib/ai_editor/review.py"
python3 "$S/build_timeline.py" <source> edits/<name> && \
python3 "$S/render.py" <source> edits/<name> && \
python3 "$PY" "$S/verify_cut.py" edits/<name> --engine <same engine as step 1> && \
python3 "$S/preview_cut.py" edits/<name> --no-open && \
python3 "$R" edits/<name> start --video edits/<name>/cut.mp4 --stage cut --transcript edits/<name>/words.json
驗證通過：剪輯頁面已準備就緒。驗證會比對剪輯後的轉錄文字與保留的文字（exit 1 會中斷鏈結）：
- MISSING：保留的文字未出現在渲染結果中。提高
--pad（或縮小範圍），重新建置與渲染。 - SURVIVED：對於真正的重複或結巴，需加入一個範圍；切勿剪掉保留的句子。
- HEARD DIFFERENTLY（「jev -> jeff」）與填充詞備註：屬於轉錄器的差異，無需重建。
- DOUBLED：連續說了兩次的詞。自然的（「非常、非常」）：保留。結巴：加入其範圍。
- N 個銜接點仍在語音中：請聆聽。如果聽起來有裁切：執行
splice_check.py edits/<name> --fix，然後重新渲染。
只進行一次修復循環（相同的鏈結），然後向使用者顯示剩餘的問題。
6. 使用者核准
鏈結已開啟審閱頁面（參閱 ../style-edit/references/review.md）。在背景中執行 serve 和 wait。告知剪掉的秒數。備註：
- 「保留 <句子>」：縮小或刪除該範圍；
- 「剪掉 <句子>」：新增一個範圍；
- 停頓不準確：
--max-pause。
然後執行步驟 4-5，對每個備註進行 resolve（使用 --reply：說明變更內容），最後執行 round --video edits/<name>/cut.mp4（切勿再次執行 start），然後詢問任何學習相關問題。
核准後，執行一個 Bash 呼叫：python3 "$S/trend.py" log edits/<name>（tally：趨勢），進行鉤子檢查。然後，如果 hooks.json 存在（參閱 references/retake-detection.md），則執行鉤子變體；由 start 呼叫，請在與 style-edit 的靜態圖表核准相同的問題框中詢問，不要提前。
只有核准才代表剪輯完成；cut.mp4 和 words.json 會傳送給 style-edit。對於「先看剪輯結果」的情況，告知使用者可以要求套用風格。請勿自行啟動 style-edit。如果由 start 呼叫：在頁面開啟時，在背景啟動 visual-prep；其 motion_briefs：同時在背景執行 clip-builder；對於 motion_note 僅提示一次。
如果腳本停止
| 訊息 | 處理方式 |
|---|---|
no such file / ffmpeg could not read audio | 詢問正確路徑；切勿複製或轉換原始檔案 |
faster-whisper missing / CrisperWhisper missing | 使用 python3 "$PY" 執行，或執行 setup 技能的步驟 3 |
no ElevenLabs key (exit 2) / HTTP 4xx, unreachable (3) | 移除 --engine scribe，或使用 setup 技能重新儲存金鑰 |
建置時對引號出現 ERROR | 修正該範圍的引號，或加入 occurrence，然後重新建置 |
cannot derive a silence threshold / marked no silence | 語音與背景差距小於 10 dB：執行 ffmpeg -i <source> -af volumedetect -vn -f null -，傳入 --noise，數值約為平均值以上 10 dB |
渲染出現 ERROR ... | 告知使用者；重新渲染一次 |
規則
- 每個剪輯都必須引用轉錄文字。沒有引用，就沒有剪輯。
- 腳本會打破素材之間的平局，並保留同一句子在腳本中出現兩次的所有素材。不會因為偏離腳本而剪掉任何內容。
- 切勿在剪輯點使用串流複製（
-c copy）：這會導致最多 2 秒的偏差。 - 切勿交付未經驗證與核准的渲染結果。
自我檢查
test_build_timeline.py、test_retakes.py、test_media.py（ffmpeg）；demo 用於 transcribe.py、trend.py、splice_check.py、script_match.py、mirror.py。