Yt2doc

yt2doc Skill

This skill converts a YouTube video into a clean, structured Markdown document using the local yt2doc CLI tool. The process downloads audio, runs transcription via Whisper, and segments the content into chapters.

Prerequisites

• yt2doc must be installed locally (e.g., via uv tool install yt2doc)
• Internet access for downloading video audio and AI models
• Sufficient local RAM for Whisper models

Step-by-Step Instructions

1. Confirm the URL and set up output path

Extract the YouTube URL from the user's message. Derive a snake_case filename from the video URL (you can use the video ID or a short descriptive name). Decide the output directory:

• Default: ./reports/YouTube_YYYY_MM_DD/ (use today's date)
• If the user specifies a directory, use that instead

Create the output directory before running the command:

mkdir -p ./reports/YouTube_YYYY_MM_DD

2. Video Strategist — Select the Right Model

Before running, apply this decision table. If the duration is unknown, look it up (e.g., via web search or yt-dlp --print duration_string). Default to the conservative path when uncertain.

Video Duration	Whisper Model	Est. Transcription Time	Min Local RAM
< 30 min	medium (default)	5–10 min	4 GB
30–60 min	small	10–20 min	6 GB
1–2 hours	small	35–55 min	8 GB
> 2 hours	base	50–80 min	10 GB

⚠️ RAM Warning: If the host machine does not have enough memory, the transcription process may be killed. Ensure you have enough free memory before running large models on long videos.

3. Tell the user what's happening

Before starting, let the user know the selected model and expected time:

"Starting yt2doc on <url>. Using the <model> model — this should take approximately X–Y minutes. I'll run it in the background and report back."

4. Run yt2doc in the background

Use run_command with a generous WaitMsBeforeAsync (5000ms is fine), then poll with command_status until done.

yt2doc \
  --video "<YouTube URL>" \
  --output ./reports/YouTube_YYYY_MM_DD/<filename>.md \
  --whisper-model <model> \
  --add-table-of-contents

Key flags:

• --whisper-model <model> — set per the Video Strategist table above (e.g., small, medium, base)
• --output ./reports/... — saves result to the correct directory
• --add-table-of-contents — adds a TOC at the top of the document (recommended)
• --timestamp-paragraphs — optionally include timestamps per paragraph (add if user asks)

⚠️ Do NOT use --segment-unchaptered unless you also have a local LLM running (e.g., Ollama) and pass --llm-model and --llm-server. This flag requires a connected LLM server and will throw LLMModelNotSpecified if omitted.

5. Poll for completion

The command can run for a long time. Use command_status with WaitDurationSeconds: 60 in a loop — check every 60 seconds until the status is DONE.

While waiting, let the user know you're still monitoring:

"Still running… (N minutes elapsed). I'll update you when it finishes."

command_status(id, WaitDurationSeconds=60)  # repeat until status == "DONE"

If the exit code is non-zero, report the error output to the user clearly.

6. Verify and report

Once done:

1. Check the output file exists and is non-empty
2. Read the first ~50 lines to confirm the document looks correct
3. Report to the user:
   • ✅ Path to the saved file
   • Title detected (usually the first # heading)
   • Number of sections/chapters found
   • Approximate word/character count (optional)

Example report:

✅ Done! Saved to ./reports/YouTube_2026_04_29/lVdajtNpaGI.md Title: 【生成式人工智慧導論2025】第2講：上下文工程 Sections: 2 chapters ~18,000 characters

Error Handling

Situation	What to do
yt2doc not found	Tell the user to install it via uv tool install yt2doc
Video is private / unavailable	Report the yt-dlp error; suggest the user check the URL
LLMModelNotSpecified error	Remove --segment-unchaptered; it requires --llm-model and --llm-server to be set
ChunkedEncodingError from HuggingFace	Network interruption during model download — retry the same command, it will resume from cache
DownloadError: downloaded file is empty	YouTube rate-limiting or signature issue — wait a few minutes and retry
Exit code non-zero (other)	Show the last 20 lines of stderr to the user

Output Format

The generated Markdown file will look like:

# [Video Title]

## Table of Contents
- [Chapter 1](#chapter-1)
- [Chapter 2](#chapter-2)

## Chapter 1
<transcribed content...>

## Chapter 2
<transcribed content...>

Do not paste the entire document into the chat. Just report the file path and key metadata.

Notes

• The AI models are pulled on first run (can take extra time if not cached)
• yt2doc uses faster-whisper by default — no GPU needed, but CPU transcription is slow for long videos
• For a ~2 hour Chinese lecture, the small model takes ~40–50 minutes on CPU with 8 GB RAM
• --segment-unchaptered uses SAT (Segment Any Text) + LLM for topic detection; only works with a local Ollama setup
• For playlists, use --playlist <url> instead of --video