Communitygithub.com

coreyhaines31/makerskills

從任何影片(YouTube、Loom、Vimeo、Riverside、Zoom 錄影、本地 MP4、X/IG 影片等 yt-dlp 支援的來源)提取內容。可選三種深度模式:逐字稿(快速免費)、視覺(逐字稿 + 畫面提取 + Claude 視覺分析關鍵時刻)、多模態(Gemini 原生影片處理或密集 Claude 視覺)。

makerskills 是什麼?

這是一個強大的 AI 技能,專為 Claude Code 等開發者工具設計,能夠從幾乎任何影片來源中提取內容並進行分析。它支援多種平台,包括 YouTube、Loom、Vimeo、Riverside、Zoom 錄影、本地檔案以及 X/IG/TikTok 等社群媒體影片。使用者可以根據需求選擇三種處理深度:快速免費的「逐字稿」模式、包含畫面提取與 Claude 視覺分析的「視覺」模式,以及使用 Gemini 原生影片處理或密集 Claude 視覺分析的「多模態」模式。此技能依賴 yt-dlp 進行下載,並優先使用平台內建字幕(如 YouTube 自動字幕),否則回退至本機 MLX-Whisper 進行轉錄,以確保速度與成本效益。處理結果會儲存在 `~/Documents/videos/` 並可選擇性地將摘要存入 Second Brain,同時與 `social-fetch`、`decide`、`pm` 及 `skillify` 等其他技能協作,形成完整的工作流程。

相容平台✓Claude Code~Codex CLI~Cursor✓Antigravity✓Gemini CLI
npx skills add https://github.com/coreyhaines31/makerskills/tree/HEAD/skills/watch-video

在你喜歡的 AI 中提問

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

說明文件

/watch-video — 以你選擇的深度轉錄與分析任何影片

取代並擴展先前的 youtube-transcript 技能。YouTube 現為眾多來源之一;深度由使用者控制。

步驟 1 — 解析輸入

接受:

  • YouTube:完整 URL、youtu.be/<id>、youtube.com/shorts/<id>、原始 11 字元 ID
  • Loom:loom.com/share/<id> 或 loom.com/embed/<id>
  • Vimeo:vimeo.com/<id>
  • Riverside:下載 URL 或本地檔案
  • Zoom:本地 .mp4(來自已下載的錄影)
  • X / IG / TikTok 影片:URL — 使用 social-fetch 取得元數據,使用 yt-dlp 取得檔案
  • 本地檔案:任何 .mp4 / .mov / .webm / .mkv 路徑

從 URL 模式或副檔名偵測來源。若有歧義,詢問使用者。

步驟 2 — 解析深度模式

觸發方式模式結果
/watch-video <url>逐字稿(預設)純文字、元數據、可選章節
/watch-video <url> transcript逐字稿與預設相同
/watch-video <url> visual視覺逐字稿 + 間隔畫面 + Claude 視覺辨識關鍵時刻
/watch-video <url> multimodal多模態原生影片傳送給 Gemini(若有 $GEMINI_API_KEY),否則使用密集 Claude 視覺逐幀分析

如果未指定深度且影片長於 10 分鐘,則在預設前先詢問(視覺/多模態模式在長影片上會產生實際費用)。

步驟 3 — 取得元數據

對於 URL 來源,使用 yt-dlp:

yt-dlp --print "%(title)s|%(uploader)s|%(duration_string)s|%(upload_date>%Y-%m-%d)s|%(description)s" \
  --print "%(chapters)j" --skip-download "<url>"

擷取:標題、上傳者/頻道、時長、上傳日期、描述(第一段)、章節(JSON 或 null)。

對於本地檔案,使用 ffprobe:

ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 "<file>"

步驟 4 — 建立工作目錄

~/Documents/videos/<source>-<slug>-<date>/

其中:

  • source:youtube / loom / vimeo / riverside / zoom / local
  • slug:標題的短橫線命名(前 4–6 個單詞,最多 50 字元)
  • date:YYYY-MM-DD

步驟 5 — 取得逐字稿

後端選擇(依序):

  1. 平台內建逐字稿(若存在且看起來完整):

    • YouTube:yt-dlp --write-sub --write-auto-sub --skip-download --sub-lang en --sub-format vtt
    • Loom:透過 https://www.loom.com/share/<id> 頁面元數據或 Loom API(若設定了 $LOOM_API_KEY)取得
    • Riverside:錄影分享頁面上有內建逐字稿
    • 若平台逐字稿存在且有時間戳記,則使用。跳過 Whisper。
  2. MLX-Whisper 本地(預設回退 — 在 Mac M 系列上快速):

    # 安裝一次:pip install mlx-whisper
    python3 -c "import mlx_whisper; mlx_whisper.transcribe('<file>', path_or_hf_repo='mlx-community/whisper-large-v3-turbo')" \
      > "<workdir>/transcript-raw.json"
    

    或透過 CLI:mlx_whisper <file> --model mlx-community/whisper-large-v3-turbo --output-dir <workdir>

  3. whisper.cpp(若 MLX 不可用時的進一步回退)

若為 URL,先下載影片檔案(使用 yt-dlp;Loom/Vimeo/YT 皆支援):

yt-dlp -f "bv*[height<=720]+ba/b[height<=720]" -o "<workdir>/video.%(ext)s" "<url>"

720p 對於轉錄和畫面分析已足夠(下載較小、處理更快)。

清理逐字稿(僅 YouTube 自動字幕需要,因為有滾動式字幕;Whisper 輸出已乾淨):

# YouTube VTT 清理 — 去除重複滾動字幕、剝離標籤、在提示間隔 >2s 處分段
awk '
  /^WEBVTT/ || /^Kind:/ || /^Language:/ || /^NOTE/ { next }
  /-->/ { in_cue = 1; last = ""; next }
  /^$/ { if (last) print last; in_cue = 0; last = ""; next }
  in_cue { gsub(/<[^>]+>/, "", $0); last = $0 }
  END { if (last) print last }
' "<workdir>/transcript.en.vtt" | awk '!seen[$0]++' > "<workdir>/transcript.txt"

最終儲存至 <workdir>/transcript.txt。

步驟 6 — 若為 transcript 模式:在此停止

輸出:

  • transcript.txt
  • metadata.json
  • 聊天中的一行摘要:標題、來源、時長、字數
  • 工作目錄路徑
  • (可選)步驟 9 — 提供儲存到 Second Brain 的選項

步驟 7 — 若為 visual 模式:提取畫面 + 視覺分析

畫面提取(ffmpeg)

根據來源啟發式設定節奏:

來源類型畫面節奏
螢幕分享 / Loom / 演示每 5 秒 1 幀(UI 變化快)
談話頭像 / 播客每 30 秒 1 幀(變化慢)
投影片簡報每 10 秒 1 幀 + 在每個偵測到的場景變化處強制一幀
不確定時預設每 15 秒 1 幀
mkdir -p "<workdir>/frames"
ffmpeg -i "<workdir>/video.mp4" -vf "fps=1/15" "<workdir>/frames/frame-%04d.png" -y

對於場景變化偵測(尤其是投影片):

ffmpeg -i "<workdir>/video.mp4" -vf "select='gt(scene,0.3)',showinfo" -vsync vfr "<workdir>/frames/scene-%04d.png" 2> "<workdir>/scene-detection.log"

視覺分析

將每幀畫面與相同時間戳窗口的逐字稿片段配對。然後批次傳送給 Claude 視覺進行綜合分析。

每批次提示(每次呼叫最多約 10 幀):

這是來自一個影片在時間戳 T1..TN 的 N 幀畫面。對於每幀畫面,用 1–2 句描述螢幕上的內容。標記:(a) 與前一幀相比的 UI 變化,(b) 螢幕上可見的文字,(c) 任何看起來像是決定、動作或值得注意的事件。也請注意在此時間窗口中說出的逐字稿文字。

將輸出儲存為 <workdir>/moments.md:

# 關鍵時刻 — <title>

## 00:00:15 (frame-001.png)
**畫面上**: 登入表單,電子郵件欄位聚焦中
**逐字稿**: 「所以你只要打開它...」
**備註**: UI 演示的開始

## 00:00:45 (frame-002.png)
**畫面上**: 包含 4 個卡片的儀表板
**逐字稿**: 「這裡你可以看到你所有的專案。」
**備註**: 主要視圖變化 — 儀表板首次出現

產生摘要

在識別出關鍵時刻後,將整個影片綜合為 <workdir>/summary.md:

# 摘要 — <title>

**來源:** <來源 URL / 檔案>
**時長:** <hh:mm:ss>
**觀看日期:** <date>
**模式:** visual

## TL;DR
<2–4 句>

## 關鍵時刻
- 00:00:15 — <一行>
- 00:00:45 — <一行>

## 標記的待辦事項
- <事項> [時間戳]

## 標記的決定
- <決定> [時間戳] — 考慮導向 /decide

## 值得保留的引述
- "..." [時間戳]

## 未解決的問題
- <提出但未回答的問題>

步驟 8 — 若為 multimodal 模式

後端選擇

  1. Gemini 原生(若設定了 $GEMINI_API_KEY;對於長影片,遠比逐幀更便宜且更快):

    預設模型:gemini-3.5-flash(2026 年 5 月發布,$1.50 輸入 / $9 輸出 每百萬 token;$0.15/秒 的影片;在編碼/代理基準測試上以 4 倍速度擊敗 3.1 Pro)。對於注重細節的品牌審查/高風險分析,覆寫為 gemini-3.1-pro;對於大量低成本處理,使用 gemini-2.5-flash-lite。

    # 步驟 1:透過 Files API 上傳影片
    FILE_URI=$(curl -s -X POST "https://generativelanguage.googleapis.com/upload/v1beta/files?key=$GEMINI_API_KEY" \
      -H "X-Goog-Upload-Command: start, upload, finalize" \
      -H "Content-Type: video/mp4" \
      --data-binary "@<workdir>/video.mp4" | jq -r '.file.uri')
    
    # 等待檔案變為 ACTIVE(Gemini 首先處理影片)
    while true; do
      STATE=$(curl -s "$FILE_URI?key=$GEMINI_API_KEY" | jq -r '.state')
      [ "$STATE" = "ACTIVE" ] && break
      sleep 3
    done
    
    # 步驟 2:使用檔案 + 多模態分析提示產生內容
    curl -s -X POST "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.5-flash:generateContent?key=$GEMINI_API_KEY" \
      -H "Content-Type: application/json" \
      -d "{
        \"contents\":[{
          \"parts\":[
            {\"file_data\":{\"mime_type\":\"video/mp4\",\"file_uri\":\"$FILE_URI\"}},
            {\"text\":\"<多模態分析提示 — 參見步驟 7 的摘要模板 + 用例擴展>\"}
          ]
        }]
      }"
    

    檔案在 Gemini Files API 中保留約 48 小時 — 可用於以不同提示重新查詢同一影片。

  2. 密集 Claude 視覺回退(若無 Gemini 金鑰):

    • 畫面節奏:每 3 秒 1 幀(比視覺模式密集得多)
    • 使用多模態分析提示批次傳送給 Claude 視覺
    • 對於長影片,比 Gemini 更慢且更昂貴 — 在對 >10 分鐘內容執行前警告使用者

多模態輸出

與步驟 7 相同的 summary.md 模板 + 一個擴展章節:

## 多模態觀察
- **肢體語言 / 表達**: <關於談話頭像影片的觀察>
- **節奏**: <快/慢/不均>
- **視覺風格**: <品牌審查、廣告評論、設計觀察>
- **音訊品質 / 氛圍**: <音樂、寂靜、背景>

確切的額外章節取決於用例(品牌審查、廣告評論、演講傳遞評論、客戶通話記錄)。用例從來源和使用者觸發時的言語框架中推斷。

步驟 9 — 可選:儲存至 Second Brain

在任何模式完成後,提供:

「要將此儲存到 Second Brain 嗎?我將寫一個 call-<slug>.md(或 meeting- / note- / resource-)到 ${SECOND_BRAIN_VAULT:-$HOME/Documents/SecondBrain}/raw/,包含摘要、來源 URL 和逐字稿連結。」

根據來源的類型前綴:

來源前綴
Loom / Zoom / Riverside / Otter / 通話錄音call-
會議(自己的筆記,非逐字稿)meeting-
演講 / 主題演講 / 會議note-
廣告 / 登陸頁面影片 / 行銷參考 / 競爭對手影片resource-

檔案內容:1 行來源、摘要、完整工作目錄的連結。

步驟 10 — 報告

在聊天中:

  • 一行標題:<來源> · <標題> · <時長> · <模式> · <字數> 個字
  • 工作目錄路徑
  • 對於 visual / multimodal:列出前 3 個關鍵時刻的簡短清單
  • 對於所有模式:任何已標記的待辦事項 / 決定,用於分流
  • 若已儲存至 Second Brain:也顯示該路徑

來源參考

來源下載內建逐字稿備註
YouTubeyt-dlp自動字幕(--write-auto-sub)與先前的 youtube-transcript 技能相同
Loomyt-dlp(支援 Loom)有 — 透過嵌入元數據或 Loom API 取得非同步螢幕分享重點 — 主要用例
Vimeoyt-dlp有時行銷/嵌入影片
Riverside來自匯出或本地檔案的直接 URL有 — Riverside 會產生它們播客集數
Zoom本地 .mp4(已下載的錄影)有時(Zoom 音訊逐字稿檔案)客戶通話
X / IG / TikTok使用 social-fetch 取得元數據,yt-dlp 取得檔案無短影音
本地檔案無無提供路徑

組合使用

  • social-fetch — 在影片處理前取得 X/IG/TikTok URL 元數據(互動、作者、回覆)
  • second-brain — 根據來源類型將摘要儲存為 raw/call-<slug>.md、meeting-、note- 或 resource-
  • decide — 當影片包含標記的決定時,導向 /decide 進行結構化擷取
  • pm — 摘要中標記的待辦事項可分流至專案看板
  • slide-deck — 演講錄音 → 大綱提取 → 投影片草稿(循環)
  • jab-hook — 來自播客/演講影片的引述 + 值得剪輯的時刻,為 BIP/推廣貼文提供素材
  • skillify from-video — 對流程錄影使用 visual 模式的主要用例。使用者記錄自己的工作流程(Loom/螢幕分享),此技能提取逐字稿 + 關鍵視覺時刻,然後 skillify 將工作流程綜合為 SKILL.md。「錄製一次,AI 轉換為技能。」

錯誤處理

失敗回應
影片不可用 / 私人 / 地區限制報告並停止
無字幕 + 未安裝 Whisper告訴使用者:pip install mlx-whisper(Mac)
ffmpeg 缺失(用於視覺/多模態模式)告訴使用者:brew install ffmpeg
視覺分析回傳空值 / 不明確降低畫面數量,重試,或回退至僅逐字稿並附上備註
請求多模態但無 $GEMINI_API_KEY 且影片 >30 分鐘警告成本,提供回退至視覺模式的選項
yt-dlp 二進位檔缺失brew install yt-dlp

關於品質的備註

  • 使用者選擇深度,而非技能。 逐字稿 / 視覺 / 多模態是三種不同的成本 + 延遲設定檔。長影片(>10 分鐘)在花費於視覺/多模態模式前總是先確認。
  • 平台逐字稿優先,Whisper 其次。 YouTube 自動字幕、Loom 逐字稿、Riverside 內建逐字稿 — 當它們存在時全部免費且即時。僅在無平台提供時回退至本地 MLX-Whisper。
  • 本地 MLX-Whisper 是 Mac 上的快速路徑。 M 系列機器轉錄速度快於即時。雲端 Whisper 是遠程的第二選擇 — 花費金錢、有網路依賴、在典型時長上延遲更差。
  • 依來源類型設定畫面節奏。 螢幕分享 / 演示需要每 5 秒 1 幀(UI 變化快);談話頭像播客需要每 30 秒 1 幀(變化慢)。不確定時預設 15 秒。錯誤的節奏 = 錯過關鍵時刻或浪費視覺分析成本。
  • 720p 已足夠。 為轉錄 + 畫面分析下載 1080p / 4K 會浪費頻寬 + 儲存空間。yt-dlp -f "bv*[height<=720]+ba/b[height<=720]" 是預設值。
  • 場景變化偵測捕獲投影片切換。 當影片是投影片簡報時,添加 ffmpeg -vf "select='gt(scene,0.3)'" 以在每個偵測到的投影片變化處強制一幀 — 比純時間取樣更可靠。
  • 多模態成本警告非選項。 Gemini 多模態處理 60 分鐘影片的成本顯著。在執行前警告;若使用者不確定,提供僅逐字稿作為回退。
  • 摘要格式包含路由提示。 ## 標記的決定 + ## 標記的待辦事項 章節為 /decide 和 /pm 後續行動提供信號。下游的可組合性存在於摘要結構中。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能