# Youtube Transcript

> Fetches YouTube transcripts as markdown using a bundled script. Use this skill whenever a YouTube transcript is needed — whether the user asks for one directly, pastes a YouTube URL and wants its content, or a transcript would help with the current task (summarising, note-taking, vault ingestion, RAG, etc.).

- Skill: `wellcaffeinated/youtube-transcript` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add wellcaffeinated/youtube-transcript`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wellcaffeinated/youtube-transcript/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: wellcaffeinated (https://skillmd.com/u/wellcaffeinated)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/wellcaffeinated/youtube-transcript

---


# YouTube Transcript

Downloads YouTube auto-captions and converts them to structured markdown via a bundled Python script. Single video → stdout (pipe to a file). Channel or playlist → one `.md` file per video written to the current directory.

**URL:** `$url` — if empty, ask the user for the URL before proceeding.

The bundled script is `scripts/yt2md.py`.

**Paths in this skill are relative to the skill's own directory, not the working directory.** Resolve `scripts/yt2md.py` against the directory this `SKILL.md` was loaded from, and use that absolute path in the commands below.

## 1. Check the dependency

The script imports `yt_dlp` as a Python package. A binary install (mise, brew) is not enough — it must be importable:

```bash
python3 -c "import yt_dlp; print(yt_dlp.version.__version__)"
```

If this errors, install it — try in order until one succeeds:

```bash
pip install yt-dlp                           # standard
pip3 install yt-dlp                          # if pip resolves to Python 2
pip install --user yt-dlp                    # no admin rights needed
pip install --break-system-packages yt-dlp  # system Python on Arch/Debian/Ubuntu
python3 -m pip install yt-dlp               # explicit interpreter fallback
```

Re-run the import check after installing before proceeding.

## 2. Run the script

Always quote URLs — `?` is a glob character in zsh/bash.

**Single video → stdout** (redirect to save):
```bash
python3 scripts/yt2md.py 'https://www.youtube.com/watch?v=ID' > transcript.md
```

**Channel or playlist → .md files in the current directory:**
```bash
python3 scripts/yt2md.py 'https://www.youtube.com/@Channel/videos'
python3 scripts/yt2md.py -n 5 'https://www.youtube.com/@Channel/videos'
```

`-n N` caps the run to the N most recent videos. Ignored for single video URLs.

Print full usage docs:
```bash
python3 scripts/yt2md.py
```

## URL patterns

| Type | Recognised forms |
|------|-----------------|
| Single video | `youtube.com/watch?v=ID` · `youtu.be/ID` · `/shorts/ID` · `/live/ID` |
| Channel | `youtube.com/@Name/videos` · `youtube.com/channel/ID` |
| Playlist | `youtube.com/playlist?list=ID` |

## Output format

Each file has YAML frontmatter (`retrieved_at`, `upload_date`, `id`, `title`, `channel`, `duration_string`, `view_count`, `tags`, `webpage_url`) followed by the transcript as prose paragraphs with `[mm:ss]` timestamp markers every ~30 seconds, then the YouTube description after `---`.

Channel output filenames are terminal-safe: `YYYYMMDD-Title-Of-Video.md`.

## Temp files

Intermediate files go to `/tmp/yt2md/` and are deleted after each video converts. The channel archive at `/tmp/yt2md/.downloaded.txt` persists so re-running the same channel URL skips already-converted videos. Delete it to re-fetch everything.