yt-drama

A Claude Code skill that prepares a portable, self-contained download script for an episodic YouTube playlist (e.g. a drama series), using yt-dlp + ffmpeg.

What it does

Point the skill at a YouTube playlist URL and it will:

1. Fetch and analyze the playlist to work out the episode structure — full vs. split episodes, part counts, gaps, and non-episode items (trailers, OSTs, previews…).
2. Check English subtitle availability and flag age-restricted or members-only videos.
3. Generate a single download_<slug>.sh script that does the rest.

The generated script

The generated script is portable — hand the one .sh file to anyone with python3 and ffmpeg installed and it runs, with no dependency on this skill:

• Provisions yt-dlp itself into a local pip-managed virtual environment (.venv-ytdlp), including curl-cffi for browser impersonation (--impersonate) to get past YouTube's anti-bot 403s. It never assumes a globally installed yt-dlp — that pip extra is the main reason for the venv.
• Checks for ffmpeg/ffprobe up front and exits with an install hint if they're missing. (ffmpeg is the one dependency it can't provision via pip.)
• Downloads full or split episodes, embedding English subtitles.
• Joins split episode parts with ffmpeg (concat, stream copy).
• Fixes metadata inline — enforces the audio track language + default disposition and the subtitle language + default/not-forced dispositions. This is built into the script; there is no separate fix_metadata.sh.
• Names files with the Plex convention: <series>/season01/<series>_s01eNN.mkv.

Everything is driven by a small config block at the top of the generated script (series name, languages, cookies, and an explicit episode → playlist-index map), so you can tweak and re-run it without regenerating.

Requirements

• python3 (a currently supported release; ≥ 3.11 recommended)
• ffmpeg / ffprobe

Install

SKILL.md lives at the repo root, so you don't need to copy any files by hand — clone the repo straight into your Claude Code skills directory.

Let Claude do it (recommended). In a Claude Code session, paste:

Clone https://github.com/<you>/yt-drama into ~/.claude/skills/yt-drama so I can use the /yt-drama skill.

Claude runs the git clone for you. Restart the session afterwards so Claude Code picks up the newly created skill directory.

Or clone it yourself:

git clone https://github.com/<you>/yt-drama ~/.claude/skills/yt-drama

Claude Code discovers the skill from ~/.claude/skills/yt-drama/SKILL.md and exposes it as /yt-drama. (Use <repo>/.claude/skills/yt-drama instead for a single project rather than your whole user account.)

Usage

Invoke /yt-drama with a YouTube playlist URL and follow the prompts.

License

GNU GPL v3.