Skip to content

coroboros/agent-skills / skills/download-media

download-media

Verified

Download video, audio, playlists, clips or subtitles from a supported URL using yt-dlp. Use when the user wants media files on disk; use MarkItDown for text extraction and the loop skills for local loop editing.

Download Media

Download video or audio from any yt-dlp-supported site using the yt-dlp CLI. The skill validates the input, composes the right flags for the intent, downloads under ~/.agents/output/<project>/download-media/<slug>/ (or a -d destination), and reports the final file paths — fully expanded, no tilde, no magic.

The deterministic work — install checks, slug derivation, destination, flag composition, final-path capture — happens in scripts/download-media.sh. The skill parses $ARGUMENTS, hands them to the script, and turns the script's RESULT: lines into a human report.

Scope

Personal and authorized use: public content, the user's own uploads, Creative Commons and licensed material. yt-dlp cannot bypass DRM and this skill never attempts to; decline requests to rip paid streaming catalogs (Netflix, Disney+, Spotify…) or to evade a site's paywall. Downloading may still be restricted by a site's terms of service and local copyright law — when a request is plainly about piracy, say so and stop.

Install

brew install yt-dlp        # macOS
pipx install yt-dlp        # any platform
brew install ffmpeg        # strongly recommended — merging, mp3 extraction, clipping

Binaries for other setups: yt-dlp releases. For full YouTube support yt-dlp also wants a JavaScript runtime (deno recommended) — see the EJS wiki. Extractors break when sites change; a failing download is often fixed by updating: brew upgrade yt-dlp or pipx upgrade yt-dlp.

Parameters

FlagDefaultEffect
-aoffAudio only, mp3 (yt-dlp preset -t mp3; needs ffmpeg; rejects the video flags -r/-b)
-boffBest native quality — skip the mp4 compatibility preset
-poffFull playlist into a <playlist title>/ subfolder, files named NNN - title [id].ext (default: single video)
-ioffInspect only — list available formats, no download; wins over the download flags
-c A-B—Clip a time range, e.g. -c 10:15-12:30 (needs ffmpeg)
-u <langs>—Subtitles as sidecar files, e.g. -u "en.*,fr" (includes auto-generated)
-r <height>—Cap resolution, e.g. -r 1080
-d <dir>convention pathDestination directory

Everything after the URL passes to yt-dlp verbatim — the escape hatch to the full CLI (see Recipes).

Default download: -t mp4 preset — h264/aac preferred, remuxed to mp4, plays everywhere. -b keeps yt-dlp's native best (often webm/mkv, higher fidelity, less compatible).

Workflow

  1. Resolve the media URL from arguments or unambiguous session context. Ask only when it is missing or ambiguous.

  2. Run the helper:

    $SKILL_DIR = this skill's folder — ${CLAUDE_SKILL_DIR} in Claude Code, the directory containing this SKILL.md elsewhere.

    bash "$SKILL_DIR"/scripts/download-media.sh -a 'https://example.com/watch?v=123&list=456'
    

    Parse arguments as data and quote each URL, path and flag value separately. Never splice raw $ARGUMENTS into shell code or use eval; URL metacharacters such as & must remain literal.

  3. The script emits RESULT: key=value lines — one path per downloaded file, then files, dest, slug (order not guaranteed; parse by key). With -i it prints yt-dlp's format table instead.

  4. Parse the RESULT: lines and produce the report below.

  5. ERR: yt-dlp not installed (exit 127) or ERR: -a and -c need ffmpeg (exit 3) → print the matching command from ## Install and stop. Never auto-install on the user's behalf.

  6. Any other ERR: (exit 2 — missing or non-URL input, unknown flag, missing flag value, invalid -r, conflicting flags) → relay the message verbatim and stop. A non-zero exit with RESULT: lines means a partial playlist success — report the downloaded files and the failure. A yt-dlp extraction failure → surface its stderr and suggest updating yt-dlp first (see Install).

Output

downloaded: <n> file(s) → <dest>
  <path>            # one line per file

Subtitle sidecars (-u) sit next to the media file but are not listed in RESULT: lines — mention they are in dest.

Examples

/download-media https://youtu.be/dQw4w9WgXcQ                 # video, mp4, best compatible
/download-media -a https://youtu.be/dQw4w9WgXcQ              # mp3
/download-media -r 1080 <url>                                 # cap at 1080p
/download-media -p <playlist-url>                             # whole playlist
/download-media -c 10:15-12:30 <url>                          # clip a segment
/download-media -u "en.*" <url>                               # video + English subtitles
/download-media -i <url>                                      # list formats, download nothing
/download-media -d ~/Downloads <url>                          # custom destination
/download-media <url> --embed-thumbnail --embed-metadata      # passthrough after the URL

Recipes — passthrough after the URL

IntentAppend after the URL
Logged-in / member content--cookies-from-browser firefox (or chrome, safari…)
Strip sponsor segments--sponsorblock-remove sponsor (needs ffmpeg)
Incremental playlist sync--download-archive <dir>/archive.txt
Split by chapters--split-chapters
Embed thumbnail + metadata--embed-thumbnail --embed-metadata
Only playlist items 3–7-I 3:7 (with -p)
Frame-accurate clip cuts--force-keyframes-at-cuts (with -c; slow, re-encodes)
Gentle on rate limits-t sleep (preset: spaced requests)
Site needs TLS impersonation--extractor-args per site, or install curl_cffi

Compose other yt-dlp flags the same way when an intent is not covered — the full option surface is yt-dlp --help.

Notes

  • Final paths are captured, not guessed — the script uses --print-to-file after_move:filepath so the reported paths are the real ones after merge/remux (--print would silence download progress).
  • Playlist URLs holding a v= too (watch-page URLs) download the single video by default; -p switches to the whole playlist.
  • Unavailable playlist entries don't lose the run — yt-dlp skips them and exits non-zero; the script still reports every downloaded file, then propagates the exit code.
  • -c takes a time range only (START-END, HH:MM:SS or seconds). Chapter-regex sections go through passthrough: --download-sections "intro".
  • Custom -o output templates passed through work, but an absolute -o makes yt-dlp ignore the destination dir (-P) — prefer -d for relocation.
  • No silent overwrites — yt-dlp skips already-downloaded files by default and the slug-namespaced destination keeps runs predictable.

Why the wrapper

yt-dlp is already a superb CLI; this skill exists to (a) put downloads under the repo's global output convention with the final paths reported deterministically, (b) translate "get me the audio" into the right preset without the user remembering -t mp3 vs -x --audio-format, and (c) keep the full flag surface reachable through verbatim passthrough instead of re-wrapping ~200 options.

reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall