UTAGE動画マニュアル作成スキル

概要

UTAGEの動画講座ページから、読みやすいマニュアルを自動作成します。

処理フロー

1. 出力フォルダの確認（ユーザーに毎回確認）
2. 講座構成の把握と計画立案（Chrome連携）
3. 各章の動画URLを取得
4. ffmpegでHLS動画をダウンロード
5. 音声を抽出
6. Groq Whisperで文字起こし
7. シーン検出でスクリーンショットを抽出
8. 読みやすい文章スタイルでマニュアル作成
9. 画像と文章の整合性チェック
10. 全章結合版の作成（オプション）

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

動画ページに移動後、readnetworkrequests で .m3u8 URLを取得:

urlPattern: ".m3u8"
→ https://s3.ap-northeast-1.wasabisys.com/utagesystem-video/.../video.m3u8

Step 4: 動画ダウンロード

スクリプト: [scripts/hlsdownloader.py](scripts/hlsdownloader.py)

# 動画ダウンロード（UTAGE/Wasabi S3向け高速設定）
python scripts/hls_downloader.py "[m3u8 URL]" "videos/[章番号]_[タイトル].mp4"

特徴:

• HTTP persistent接続で高速ダウンロード
• コピーモード（再エンコードなし）
• 自動リトライ対応

Step 5: 音声抽出

スクリプト: [scripts/hlsdownloader.py](scripts/hlsdownloader.py)

# 動画から音声を抽出（MP3形式）
python scripts/hls_downloader.py --extract-audio "videos/[章番号]_[タイトル].mp4" "audio/[章番号].mp3"

Step 6: 文字起こし

スクリプト: [scripts/transcribe.py](scripts/transcribe.py)

# Groq Whisperで文字起こし
python scripts/transcribe.py "audio/[章番号].mp3" "transcripts/[章番号].txt"

特徴:

• 3分チャンクで分割（安定性重視）
• 並列処理（チャンク数に応じて3〜10並列）
• レート制限時は自動リトライ
• GROQAPIKEYは.envファイルから自動読み込み

Step 7: スクリーンショット抽出

スクリプト: [scripts/screenshotextractor.py](scripts/screenshotextractor.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](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: 抽出した画像を確認してマニュアルに追加

1. Readツールで抽出した画像を確認
2. 適切な画像をマニュアルの該当箇所に追加
3. 画像の内容に言及する文章も追加

![設定画面](../screenshots/XX/ts_001_00180.jpg)

上の画像にあるように、この設定画面では〜

9-1-2. 画像が必要な典型的なパターン

以下のパターンでは画像が必須:

1. 操作手順: 「タップ」「クリック」「選択」などの動作がある場合
2. 設定変更: 「オンにする」「チェックを入れる」などの場合
3. 画面説明: 「この画面」「ここに表示される」などの場合
4. 比較説明: 「Before/After」「変更前/変更後」の場合
5. 複雑な概念: 図解があると理解しやすい場合

9-2. 読みやすさチェック

確認項目:

• 箇条書きが3つ以上連続していないか
• 表が2つ以上連続していないか
• セクション間の繋がりは自然か（「では」「さて」「ここで」などの接続）
• 動画の語り口調が活きているか
• 最後に明確なアクション（次にやること）があるか

9-3. 整合性チェック

MANDATORY: [image-alignment.md](image-alignment.md) を読むこと。

1. 各画像の内容を確認: Readツールで画像ファイルを読み込む
2. 画像内のテキスト・図を把握: タイトル、見出し、図解の内容をメモ
3. 整合性を確認: 画像を参照する箇所の文章が、画像の内容と一致しているか
4. 不一致があれば修正: 画像の内容に合わせて文章を調整

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対照表

Step 10: 全章結合版の作成（オプション）

全章のマニュアルを1つのファイルに結合:

# [講座名] 完全マニュアル

## 目次

[各章へのリンクを生成]

---

# 第X章：[タイトル]

[各章のマニュアル内容を結合]

...

必要環境

• GROQAPIKEY（.envファイルに保存済み）
• ffmpeg（動画処理）
• Python 3 + requests（文字起こしスクリプト用）
• Chrome + Claude in Chrome拡張機能

スクリプト一覧

インストール

# 必要なPythonパッケージ
pip install requests

# ffmpegのインストール（macOS）
brew install ffmpeg