Video Download

Video Download Skill

Wraps yt-dlp with automatic recovery for YouTube anti-bot challenges.

Tool

scripts/download.py — installs yt-dlp on first run, merges video+audio to MP4, auto-rotates strategies on bot detection, uses a download-archive for safe resume.

Workflow

1. Collect all URLs from the user's request.
2. Determine output directory (current working directory if unspecified).
3. Decide single-video vs playlist mode:

• User says "this video" / single URL → leave default (single-video).
• User says "playlist" / "all videos" / passes a playlist?list= URL → add --playlist.

1. Run the script. If YouTube bot detection hits, the script auto-rotates strategies.
2. Report which files were saved and which strategy worked.

Usage

# Single video, current directory
python scripts/download.py "https://www.youtube.com/watch?v=..."

# Multiple URLs to a folder
python scripts/download.py "URL1" "URL2" -o "/path/to/output"

# Full playlist as 720p MP4
python scripts/download.py "https://www.youtube.com/playlist?list=..." --playlist -o "./out"

# Force a specific browser for cookies (skips auto-rotation)
python scripts/download.py "URL" --cookies-from-browser chrome

# Force a manual cookies.txt file
python scripts/download.py "URL" --cookies "~/Downloads/www.youtube.com_cookies.txt"

# Higher quality
python scripts/download.py "URL" --max-height 1080

Flags

| Flag | Default | Notes | |---|---|---| | -o, --output | cwd | Output directory | | --max-height | 720 | Max video height (e.g. 1080, 480) | | --playlist | off | Download full playlist; default is single-video | | --cookies-from-browser | auto | Force one browser; skips auto-rotation | | --cookies | auto | Force one cookies.txt file; skips auto-rotation | | --no-archive | off | Disable .download-archive.txt resume tracking |

Auto-Recovery Strategy Chain

When a request fails with bot-detection markers (Sign in to confirm, LOGIN_REQUIRED), the script automatically advances through these strategies in order, stopping at the first one that succeeds:

1. No auth + throttle — Default. Sleep intervals between requests.
2. Player client rotation — default,tv,mweb,web_safari. Bypasses softer blocks.
3. Browser cookies rotation — Tries chrome → edge → firefox → brave → vivaldi → opera,

only browsers actually installed on the system.

1. Cookies file discovery — Picks the newest valid cookies file from

~/Downloads/www.youtube.com_cookies.txt, youtube*cookies*.txt, cookies.txt (

• Firefox: "cookies.txt" —

1. Open in that browser, signed in to a Google

account.

1. Click the extension's toolbar icon:

• "Get cookies.txt LOCALLY" → "Export As" → Netscape format → use the

"Current Site" option so only youtube.com cookies are included.

• Firefox "cookies.txt" → "Current Site" → Save.

1. Save the file to the OS default Downloads folder. Any of these names work

(auto-detected, newest wins):

• www.youtube.com_cookies.txt (extension default — easiest)
• youtube.com_cookies.txt
• cookies.txt

1. Re-run the same download command. Strategy 4 picks the file up

automatically.

When to recommend each alternative

• Close the browser (Chrome / Edge): fastest fix on Windows, where

App-Bound Encryption locks the cookie database while the browser runs. Costs the user their open tabs unless "Continue where you left off" is enabled.

• Different network (mobile hotspot, VPN): bypasses an IP-level block.

Fastest if the user already has a VPN.

• Wait it out: YouTube IP blocks lift on their own, usually within 24 h.

Recommend only if no other option fits.

Resume / Re-Run Safety

--download-archive .download-archive.txt is enabled by default. Already-downloaded videos are skipped on re-runs, so it's safe to re-run after partial failure or when adding more URLs to the same folder. Pass --no-archive to disable.

Output Filename Pattern

• Single video: {title} [{id}].mp4
• Playlist: {NNN} - {title} [{id}].mp4 (zero-padded index keeps order in file managers)

--windows-filenames is always on, so files are safe across OSes.

Authentication Notes

• Auto-rotation handles most cases without user input.
• --cookies-from-browser chrome requires Chrome closed on Windows

(App-Bound Encryption locks the cookie DB while Chrome is running).

• If Chrome must stay open, recommend the user export cookies via the

"Get cookies.txt LOCALLY" Chrome extension and drop the file in ~/Downloads/. The script picks it up automatically on next run.

Supported Platforms

YouTube (single + playlists), Instagram, TikTok, Twitter/X, Facebook, Vimeo, Reddit, and 1000+ more via yt-dlp.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: maystudios
• Source: maystudios/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.