Overview
Automatically create readable manuals from UTAGE video course pages.
Processing Flow
- Confirm output folder(confirm with the user every time)
- Understand course structure and formulate a plan(Chrome integration)
- Get the video URL for each chapter
- Download HLS videos with ffmpeg
- Extract audio
- Transcribe with Groq Whisper
- Extract screenshots with scene detection
- Create the manual in a readable writing style
- Check consistency between images and text
- Create a combined version of all chapters (optional)
Step 1: Confirm the course page and output destination
MANDATORY: Before starting processing, always confirm with the user.
📚 講座ページのURLを教えてください
（例: https://utage-system.com/members/xxxxx/course/xxxxx）
📁 出力先フォルダ: [現在のディレクトリ]/[講座名]_manual/
（変更したい場合は教えてください）
Note: After receiving the course URL from the user, access the course page via Chrome integration.
Output file structure (example)
⚠️ The following is anexampleof the folder structure. The actual folder names and file names will vary depending on the course content.
[出力フォルダ]/
├── videos/
│ ├── [章番号]_[タイトル].mp4
│ └── ...
├── audio/
│ ├── [章番号].mp3
│ └── ...
├── transcripts/
│ ├── [章番号].txt
│ └── ...
├── screenshots/
│ ├── [章番号]/
│ │ ├── title.jpg
│ │ ├── frame_001.jpg
│ │ └── ...
│ └── ...
├── manuals/
│ ├── [章番号]_[タイトル].md
│ └── ...
└── full_manual.md # 全章結合版
Step 2: Understand course structure and formulate a plan
2-1. Access the course page
// tabs_context_mcp でタブ情報を取得
// navigate で講座ページに移動
// read_page でページ構造を取得
2-2. Extract the chapter list
// 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. Create a processing plan
Present the extracted chapter list to the user and get confirmation:
📋 講座構成（全N章）
[抽出した章一覧を表示]
処理対象を選択してください:
- 全章処理
- 特定の章のみ（番号指定）
- 範囲指定（例: 0-5）
Step 3: Get video URLs
Get the video URL from each chapter's lesson page:
// iframeから動画URLを取得
const iframe = document.querySelector('iframe');
iframe.src // → https://utage-system.com/video/xxxxx
After navigating to the video page,read_network_requests で .m3u8 get the URL:
urlPattern: ".m3u8"
→ https://s3.ap-northeast-1.wasabisys.com/utagesystem-video/.../video.m3u8
Step 4: Download videos
Script: scripts/hls_downloader.py
# 動画ダウンロード（UTAGE/Wasabi S3向け高速設定）
python scripts/hls_downloader.py "[m3u8 URL]" "videos/[章番号]_[タイトル].mp4"
Features:
- High-speed download via HTTP persistent connection
- Copy mode (no re-encoding)
- Automatic retry support
Step 5: Extract audio
Script: scripts/hls_downloader.py
# 動画から音声を抽出（MP3形式）
python scripts/hls_downloader.py --extract-audio "videos/[章番号]_[タイトル].mp4" "audio/[章番号].mp3"
Step 6: Transcription
Script: scripts/transcribe.py
# Groq Whisperで文字起こし
python scripts/transcribe.py "audio/[章番号].mp3" "transcripts/[章番号].txt"
Features:
- Split into 3-minute chunks (prioritizing stability)
- Parallel processing (3 to 10 parallel depending on the number of chunks)
- Automatic retry when rate-limited
- GROQ_API_KEYは
.envAutomatically load from file
Step 7: Screenshot extraction
Script: 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
Features:
- Accurately detects slide changes and UI changes in pHash mode (default)
- Automatically eliminates duplicate frames (solves the weakness of the 30-second interval method)
- The number of images is automatically adjusted according to the amount of content change (slide-focused = fewer, demo-focused = more)
- Requires imagehash + Pillow (
pip install imagehash Pillow）
Step 8: Manual creation
MANDATORY: writing-style.md Read this.
Rules for writing style
- Avoid excessive use of bullet points and tables
- Explain in a flowing prose style
- Make use of the video's conversational tone
- Use questions directed at the reader
- Present a clear action at the end
Step 9: Manual Review and Revision
BLOCKER: Review after manual generation is mandatory. Generation complete ≠ done. When delegating to each Agent, always include the following in the Agent prompt:
- "Always read writing-style.md and image-alignment.md"
- "Do not report completion until all items in the Step 9 review checklist have been passed"
- "Check the consistency between images and text while verifying the image content"
MANDATORY: After creating the manual, always perform the following review and fix any issues.
9-1. Image Check
Required Check Items:
- Is at least one image placed in each section?
- Are the image paths correct (
../screenshots/XX/frame_XXX.jpgformat) - Does the text mention the content of the image (e.g., "as shown in the image above")?
# 画像の参照数を確認
grep -c "!\[" manuals/[章番号]_*.md
# 各セクション（##）に画像があるか確認
grep -E "^##|!\[" manuals/[章番号]_*.md
9-1-1. Handling Insufficient Images
If images are insufficient, add them using the following procedure:
Step 1: Identify locations requiring images from the transcript
Read the transcript and identify locations such as the following:
- Explanations of operation procedures (e.g., "tap here", "on this screen")
- Explanations of settings screens
- References to diagrams or slides
- Explanations of tool interfaces
Step 2: Estimate the necessary timestamps
From the position in the transcript, estimate the approximate timestamp in the video:
- Calculate the ratio from the total length of the transcript and the position of the relevant location
- Multiply the video length by the ratio to calculate the approximate number of seconds
Example: If the entire transcript is 3000 characters, the relevant location is around the 1500th character, and the video is 10 minutes (600 seconds) → 1500/3000 × 600 = around 300 seconds (5 minutes)
Step 3: Extract additional screenshots
# 特定のタイムスタンプでフレームを抽出
python scripts/screenshot_extractor.py "videos/[章番号]_[タイトル].mp4" "screenshots/[章番号]" --timestamps "120,180,240,300"
# または、より細かい間隔で再抽出（例: 15秒間隔）
python scripts/screenshot_extractor.py "videos/[章番号]_[タイトル].mp4" "screenshots/[章番号]" --interval 15
Step 4: Check the extracted images and add them to the manual
- Check the extracted images with the Read tool
- Add appropriate images to the relevant locations in the manual
- Also add text that mentions the content of the images
上の画像にあるように、この設定画面では〜
9-1-2. Typical Patterns Requiring Images
Images are mandatory for the following patterns:
- Operation procedures: When there are actions such as "tap", "click", "select", etc.
- Settings changes: When there are actions such as "turn on", "check the box", etc.
- Screen explanations: When there are phrases such as "this screen", "displayed here", etc.
- Comparison explanations: In the case of "Before/After" or "変更前/変更後"
- Complex concepts: When diagrams make them easier to understand
9-2. Readability check
Check items:
- Are there three or more consecutive bullet lists?
- Are there two or more consecutive tables?
- Are the connections between sections natural (transitions such as "Now then," "Well then," "Here")?
- Is the video's speaking tone brought to life?
- Is there a clear action (what to do next) at the end?
9-3. Consistency check
MANDATORY: image-alignment.md Read.
- Check the content of each image: Load the image file with the Read tool
- Understand the text and diagrams in the image: Note the title, headings, and diagram content
- Check consistency: Whether the text in the section referencing the image matches the image content
- Fix any discrepancies: Adjust the text to match the image content
9-4. Making corrections
If problems are found in the review,be sure to fix them before proceeding to the next chapter。
✅ レビュー完了チェックリスト
- 画像: 各セクションに配置済み
- 読みやすさ: 箇条書き過多なし、セクション接続OK
- 整合性: 画像と文章の内容が一致
Required instruction template when delegating to Agents
When distributing manual generation across multiple Agents, follow the template below:
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 comparison table
| NG | OK | Reason |
|---|---|---|
| Requesting manual generation from an Agent without review instructions | Review instructions required | Without review, consistency breaks down |
| Guessing from the file name without reading the image | Always check image content with Read | File names do not represent content |
| Generating without reading writing-style.md | Always read it first | For style consistency |
Step 10: Creating a combined version of all chapters (optional)
Combine the manuals for all chapters into one file:
# [講座名] 完全マニュアル
## 目次
[各章へのリンクを生成]
---
# 第X章：[タイトル]
[各章のマニュアル内容を結合]
...
Required environment
- GROQ_API_KEY（
.envsaved to file) - ffmpeg (video processing)
- Python 3 + requests (for transcription scripts)
- Chrome + Claude in Chrome extension
Script list
| Script | Purpose |
|---|---|
scripts/hls_downloader.py |
HLS video download + audio extraction |
scripts/transcribe.py |
Groq Whisper transcription (parallel processing) |
scripts/screenshot_extractor.py |
Screenshot extraction (interval/scene detection) |
Installation
# 必要なPythonパッケージ
pip install requests
# ffmpegのインストール（macOS）
brew install ffmpeg