naoterumaker UTAGE動画マニュアル作成スキル
概要
UTAGEの動画講座ページから、読みやすいマニュアルを自動作成します。
処理フロー
- 出力フォルダの確認（ユーザーに毎回確認）
- 講座構成の把握と計画立案（Chrome連携）
- 各章の動画URLを取得
- ffmpegでHLS動画をダウンロード
- 音声を抽出
- Groq Whisperで文字起こし
- シーン検出でスクリーンショットを抽出
- 読みやすい文章スタイルでマニュアル作成
- 画像と文章の整合性チェック
- 全章結合版の作成（オプション）
Step 1: 講座ページと出力先の確認
MANDATORY: 処理を開始する前に、必ずユーザーに確認する。
📚 講座ページのURLを教えてください
（例: https://utage-system.com/members/xxxxx/course/xxxxx）
📁 出力先フォルダ: [現在のディレクトリ]/[講座名]_manual/
（変更したい場合は教えてください）
注意: ユーザーから講座URLを受け取ってから、Chrome連携で講座ページにアクセスする。
出力ファイル構成（例）
⚠️ 以下はフォルダ構成の例です。実際のフォルダ名・ファイル名は講座内容に応じて変わります。
[出力フォルダ]/
├── videos/
│ ├── [章番号]_[タイトル].mp4
│ └── ...
├── audio/
│ ├── [章番号].mp3
│ └── ...
├── transcripts/
│ ├── [章番号].txt
│ └── ...
├── screenshots/
│ ├── [章番号]/
│ │ ├── title.jpg
│ │ ├── frame_001.jpg
│ │ └── ...
│ └── ...
├── manuals/
│ ├── [章番号]_[タイトル].md
│ └── ...
└── full_manual.md # 全章結合版
Step 2: 講座構成の把握と計画立案
2-1. 講座ページにアクセス
// tabs_context_mcp でタブ情報を取得
// navigate で講座ページに移動
// read_page でページ構造を取得
2-2. 章一覧を抽出
// javascript_tool で章リストを取得
const lessons = document.querySelectorAll('a[href*="/lesson/"]');
const chapters = Array.from(lessons).map((a, i) => ({
index: i,
title: a.textContent.trim(),
url: a.href
}));
JSON.stringify(chapters);
2-3. 処理計画を作成
抽出した章一覧をユーザーに提示し、確認を取る:
📋 講座構成（全N章）
[抽出した章一覧を表示]
処理対象を選択してください:
- 全章処理
- 特定の章のみ（番号指定）
- 範囲指定（例: 0-5）
Step 3: 動画URL取得
各章のレッスンページから動画URLを取得:
// iframeから動画URLを取得
const iframe = document.querySelector('iframe');
iframe.src // → https://utage-system.com/video/xxxxx
動画ページに移動後、read_network_requests で .m3u8 URLを取得:
urlPattern: ".m3u8"
→ https://s3.ap-northeast-1.wasabisys.com/utagesystem-video/.../video.m3u8
Step 4: 動画ダウンロード
スクリプト: scripts/hls_downloader.py
# 動画ダウンロード（UTAGE/Wasabi S3向け高速設定）
python scripts/hls_downloader.py "[m3u8 URL]" "videos/[章番号]_[タイトル].mp4"
特徴:
- HTTP persistent接続で高速ダウンロード
- コピーモード（再エンコードなし）
- 自動リトライ対応
Step 5: 音声抽出
スクリプト: scripts/hls_downloader.py
# 動画から音声を抽出（MP3形式）
python scripts/hls_downloader.py --extract-audio "videos/[章番号]_[タイトル].mp4" "audio/[章番号].mp3"
Step 6: 文字起こし
スクリプト: scripts/transcribe.py
# Groq Whisperで文字起こし
python scripts/transcribe.py "audio/[章番号].mp3" "transcripts/[章番号].txt"
特徴:
- 3分チャンクで分割（安定性重視）
- 並列処理（チャンク数に応じて3〜10並列）
- レート制限時は自動リトライ
- GROQ_API_KEYは
.envファイルから自動読み込み
Step 7: スクリーンショット抽出
スクリプト: scripts/screenshot_extractor.py
# pHashモード（デフォルト・推奨）: スライド変化を検出して重複を排除
python scripts/screenshot_extractor.py "videos/[章番号]_[タイトル].mp4" "screenshots/[章番号]"
# pHash閾値を調整（デフォルト=8, 小さいほど多く取る）
python scripts/screenshot_extractor.py "videos/[章番号]_[タイトル].mp4" "screenshots/[章番号]" --phash-threshold 6
# レガシーモード: 30秒間隔（pHashが使えない環境用）
python scripts/screenshot_extractor.py "videos/[章番号]_[タイトル].mp4" "screenshots/[章番号]" --no-phash --interval 30
特徴:
- pHashモード（デフォルト）でスライド切替・UI変化を正確に検出
- 重複フレームを自動で排除（30秒間隔方式の弱点を解消）
- コンテンツ変化量に応じて枚数が自動調整される（スライド中心=少なめ、デモ中心=多め）
- imagehash + Pillow が必要（
pip install imagehash Pillow）
Step 8: マニュアル作成
MANDATORY: writing-style.md を読むこと。
文章スタイルのルール
- 箇条書き・表の多用は避ける
- 文章で流れるように説明
- 動画の語り口調を活かす
- 読者への問いかけを使う
- 最後に明確なアクションを提示
Step 9: マニュアルのレビューと修正
BLOCKER: マニュアル生成後のレビューは必須。生成完了 ≠ 完了。 各Agentに委譲する場合も、Agentプロンプトに必ず以下を含めること:
- "writing-style.md と image-alignment.md を必ず読むこと"
- "Step 9のレビューチェックリストを全項目通過するまで完了報告しないこと"
- "画像と文章の整合性を画像内容を確認しながらチェックすること"
MANDATORY: マニュアル作成後、必ず以下のレビューを実施し、問題があれば修正すること。
9-1. 画像チェック
必須確認項目:
- 各セクションに最低1枚は画像が貼られているか
- 画像パスが正しいか（
../screenshots/XX/frame_XXX.jpg形式） - 画像の内容に文章で言及しているか（「上の画像にあるように〜」など）
# 画像の参照数を確認
grep -c "!\[" manuals/[章番号]_*.md
# 各セクション（##）に画像があるか確認
grep -E "^##|!\[" manuals/[章番号]_*.md
9-1-1. 画像が不足している場合の対処
画像が不足している場合は、以下の手順で追加する:
手順1: 文字起こしから画像が必要な箇所を特定
文字起こしを読み、以下のような箇所を特定:
- 操作手順の説明（「ここをタップして」「この画面で」など）
- 設定画面の説明
- 図解やスライドへの言及
- ツールのインターフェース説明
手順2: 必要なタイムスタンプを推定
文字起こしの位置から、動画内のおおよそのタイムスタンプを推定:
- 文字起こしの全体の長さと、該当箇所の位置から割合を計算
- 動画の長さに割合を掛けて、おおよその秒数を算出
例: 文字起こし全体が3000文字、該当箇所が1500文字目付近、動画が10分(600秒)の場合 → 1500/3000 × 600 = 300秒(5分)付近
手順3: 追加のスクリーンショットを抽出
# 特定のタイムスタンプでフレームを抽出
python scripts/screenshot_extractor.py "videos/[章番号]_[タイトル].mp4" "screenshots/[章番号]" --timestamps "120,180,240,300"
# または、より細かい間隔で再抽出（例: 15秒間隔）
python scripts/screenshot_extractor.py "videos/[章番号]_[タイトル].mp4" "screenshots/[章番号]" --interval 15
手順4: 抽出した画像を確認してマニュアルに追加
- Readツールで抽出した画像を確認
- 適切な画像をマニュアルの該当箇所に追加
- 画像の内容に言及する文章も追加
上の画像にあるように、この設定画面では〜
9-1-2. 画像が必要な典型的なパターン
以下のパターンでは画像が必須:
- 操作手順: 「タップ」「クリック」「選択」などの動作がある場合
- 設定変更: 「オンにする」「チェックを入れる」などの場合
- 画面説明: 「この画面」「ここに表示される」などの場合
- 比較説明: 「Before/After」「変更前/変更後」の場合
- 複雑な概念: 図解があると理解しやすい場合
9-2. 読みやすさチェック
確認項目:
- 箇条書きが3つ以上連続していないか
- 表が2つ以上連続していないか
- セクション間の繋がりは自然か（「では」「さて」「ここで」などの接続）
- 動画の語り口調が活きているか
- 最後に明確なアクション（次にやること）があるか
9-3. 整合性チェック
MANDATORY: image-alignment.md を読むこと。
- 各画像の内容を確認: Readツールで画像ファイルを読み込む
- 画像内のテキスト・図を把握: タイトル、見出し、図解の内容をメモ
- 整合性を確認: 画像を参照する箇所の文章が、画像の内容と一致しているか
- 不一致があれば修正: 画像の内容に合わせて文章を調整
9-4. 修正の実施
レビューで問題が見つかった場合は、必ず修正してから次の章に進む。
✅ レビュー完了チェックリスト
- 画像: 各セクションに配置済み
- 読みやすさ: 箇条書き過多なし、セクション接続OK
- 整合性: 画像と文章の内容が一致
Agent委譲時の必須指示テンプレート
マニュアル生成を複数Agentに分散する場合、以下のテンプレートに従う:
Agent(
model: "sonnet",
prompt: """
必ず以下を読んでから生成開始:
- ~/.claude/skills/utage-manual/writing-style.md
- ~/.claude/skills/utage-manual/image-alignment.md
生成対象: ch{N}-{M}
各章について:
1. transcript.txt 全文読込 (BLOCKER)
2. screenshots/ から最低5枚をRead (画像内容把握 - BLOCKER)
3. マニュアル生成 (writing-style.md準拠)
4. レビュー実施:
- 各セクションに画像があるか
- 画像と文章の内容が整合しているか
- 箇条書き3つ以上連続していないか
- 流れる文章になっているか
5. レビューで問題があれば修正してから完了報告
完了報告時にレビュー結果も含めること。
"""
)
NG/OK対照表
| NG | OK | 理由 |
|---|---|---|
| Agentにマニュアル生成依頼するときレビュー指示なし | レビュー指示必須 | レビューなしだと整合性破綻 |
| 画像を読まずにファイル名から推測 | 必ずReadで画像内容確認 | ファイル名は内容を表さない |
| writing-style.md読まずに生成 | 必ず読んでから | スタイル一貫性のため |
Step 10: 全章結合版の作成（オプション）
全章のマニュアルを1つのファイルに結合:
# [講座名] 完全マニュアル
## 目次
[各章へのリンクを生成]
---
# 第X章：[タイトル]
[各章のマニュアル内容を結合]
...
必要環境
- GROQ_API_KEY（
.envファイルに保存済み） - ffmpeg（動画処理）
- Python 3 + requests（文字起こしスクリプト用）
- Chrome + Claude in Chrome拡張機能
スクリプト一覧
| スクリプト | 用途 |
|---|---|
scripts/hls_downloader.py |
HLS動画ダウンロード＋音声抽出 |
scripts/transcribe.py |
Groq Whisper文字起こし（並列処理） |
scripts/screenshot_extractor.py |
スクリーンショット抽出（間隔/シーン検出） |
インストール
# 必要なPythonパッケージ
pip install requests
# ffmpegのインストール（macOS）
brew install ffmpeg