agentleFS
coroboroscoroboros/agent-skills/skills/download-media/SKILL.md

download-media

Skill4 starsChanged 18 days agoMITView on GitHub

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.

  • Installs packages

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Default download: -t mp4 preset — h264/aac preferred, remuxed to mp4, plays everywhere.

    line 49

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.