agentleFS
johnqtcgjohnqtcg/awesome-skills/skills/yt-dlp-downloader/SKILL.md

yt-dlp-downloader

Skill30 starsChanged 4 months agoMITView on GitHub

Generate and run yt-dlp download commands with probe-driven format selection, safe output naming, retry defaults, and structured execution reports. Use when users want to download videos, extract audio, fetch playlists, grab subtitles, handle authenticated/age-gated content, or download live streams. Covers single videos, playlists, audio extraction, subtitle-inclusive downloads, format-ID / resolution-capped downloads, SponsorBlock integration, live streams, and browser-cookie authentication.

  • Installs packages

5 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use agent-browser.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • VercelSkill

    agent-browser

    Automates browser interactions for web testing, form filling, screenshots, and data extraction. Use when the user needs to navigate websites, interact with web pages, fill forms, take screenshots, test web applications, or extract information from web pages.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

26 rules. 0 are common, 13 are distinctive, and 13 are very specific to this project.

  • 0

    Common

    Most of the 5 edited versions we read keep these.

  • 13

    Distinctive

    This author's own choices. Worth a look.

  • 13

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Composite requests: When multiple scenarios apply (e.g., playlist + resolution cap + subtitles), choose the primary scenario as the …

    line 60
  2. Very specific:

    ffmpeg is required: when: merging video+audio (-f bv*+ba), embedding subtitles (--embed-subs), extracting audio (-x), embedding thumbnails …

    line 71
  3. Very specific:

    If a dependency is missing: state Not available in this environment, name the exact missing dependency, and provide the install command.

    line 98
  4. Distinctive:

    STOP and ASK: if:

    line 102
  5. Distinctive:

    Do not guess format availability.

    line 120
  6. Distinctive:

    Use cookies only for content the user is authorized to access

    line 134
  7. Very specific:

    Prefer --cookies-from-browser <browser> over raw cookie files

    line 135
  8. Distinctive:

    Never: ask the user to paste cookie contents into chat

    line 136
  9. Distinctive:

    If auth is required but unavailable, stop at the command recommendation

    line 139
  10. Distinctive:

    Never claim a download succeeded unless the command actually ran.

    line 153
  11. Very specific:

    When logging is useful (batch, troubleshooting, unstable network), tee the output — but set pipefail first, or the shell reports tee's exit …

    line 170
  12. Very specific:

    If pipefail is unavailable (plain sh, some CI runners), use yt-dlp's own sink instead of a pipe: --print-to-file "%(filepath)s" …

    line 179
  13. Distinctive:

    Never report download success, file size, or format availability in Degraded or Blocked mode.

    line 212
  14. Distinctive:

    Never help download content the user is not authorized to access

    line 216
  15. Distinctive:

    Never describe cookies as a DRM/paywall bypass method

    line 217
  16. Distinctive:

    Never claim a download ran unless it actually executed

    line 219
  17. Distinctive:

    Never hardcode format IDs without probing the specific video

    line 220
  18. Very specific:

    Always include --no-playlist for single-video watch URLs with playlist parameters

    line 221
  19. Very specific:

    Always verify ffmpeg before merge/extract/embed operations

    line 222
  20. Very specific:

    Always pair --embed-subs with --write-subs (or --write-auto-subs) — --embed-subs alone does not download subtitles

    line 223
  21. Distinctive:

    Every response must include these 7 fields:

    line 227
  22. Very specific:

    When the output contract's shape is unclear, or the scenario is composite: → Load references/golden-examples.md for fully worked examples …

    line 255
  23. Very specific:

    When choosing between format selectors, playlist modes, or subtitle strategies: → Load references/decision-rules.md for decision trees …

    line 259
  24. Very specific:

    When the request specifies quality, codec, HDR, AV1, or specific resolution: → Load references/format-selection-guide.md for probe output …

    line 262
  25. Very specific:

    When the user reports auth errors, extraction failures, or throttling, or when cookies or private content are involved: → Load …

    line 265
  26. Very specific:

    When reviewing or self-checking a generated command for common mistakes: → Load references/anti-examples.md for the remaining 5 of the 9 …

    line 268

“Common” is measured: kept by at least 6 in 10 of the 5 edited versions of this file we could read. “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

yt-dlp Downloader

Probe-driven download workflow with explicit format selection and safe retry defaults.

Quick Reference

If you need to…Go to
Choose scenario (single video / audio / playlist / subtitles / live / SponsorBlock)§1 Scope Classification
Handle specific resolution, codec, HDR, or AV1Load references/format-selection-guide.md
Handle private / age-gated / login-required content§5 Auth Safety Gate + Load references/safety-and-recovery.md
Fix extraction errors, throttling, or YouTube failuresLoad references/safety-and-recovery.md
Check the output contract fields (Scenario / Probe / Command…)§Output Contract

Mandatory Gates

Gates execute in strict serial order. Any gate failure blocks all subsequent steps.

1) Scope         2) Dependency    3) Ambiguity     4) Probe
   Classification → Check       → Resolution    → Before Download
   │                │              │               │
   scenario type    yt-dlp+ffmpeg  unclear?        -F / --list-subs
   → classify       → verify      → STOP+ASK      → inspect first
        │                │              │               │
        5) Auth Safety   6) Execution   7) Execution
           Gate        →    Mode      →    Integrity
           │                │              │
           cookies/DRM      full/degraded  actually ran?
           → enforce        → auto-select  → report honestly

1) Scope Classification Gate

Map every request into exactly one scenario before proceeding:

ScenarioTrigger
Single videoOne URL, default quality or specific format
Fixed resolutionUser mentions 720p, 1080p, 4K, or specific codec
PlaylistPlaylist URL, "all videos", "course", "channel"
Audio extraction"mp3", "audio only", "podcast", "music"
Subtitles"subtitles", "captions", "srt", specific language
Authenticated"private", "members-only", "age-gated", login required
Live stream"live", "stream", "premiere", "currently streaming"
SponsorBlock"skip sponsors", "remove intros", "no ads"

Goal: Determine which scenario template to use from references/scenario-templates.md.

Composite requests: When multiple scenarios apply (e.g., playlist + resolution cap + subtitles), choose the primary scenario as the template base (typically the delivery mechanism — single video, playlist, or audio extraction), then overlay flags from secondary scenarios. Document the composition in the Output Contract's Scenario field.

2) Dependency Gate

Before execution, verify:

yt-dlp --version
ffmpeg -version

ffmpeg is required when: merging video+audio (-f bv*+ba), embedding subtitles (--embed-subs), extracting audio (-x), embedding thumbnails (--embed-thumbnail), or using --merge-output-format.

yt-dlp-ejs + JS runtime: Full YouTube support requires yt-dlp-ejs and a JavaScript runtime. Runtimes are tried in priority order deno > node > quickjs > bun, and only deno is enabled by default — to use a lower-priority one, pass --no-js-runtimes before --js-runtimes <name>.

Minimum versions, from the yt-dlp/ejs "Runtime requirements" table (not the "Development requirements" table below it, which is stricter and applies to developing ejs itself):

RuntimeRequiredNote
deno>=2.3recommended
node>=22
bun>=1.2.11, <=1.3.14deprecated
quickjssee the ejs READMEsupported, lowest priority
pip install yt-dlp-ejs
# deno >= 2.3 recommended; node >= 22 also works

Version floors move with ejs releases — confirm against https://github.com/yt-dlp/ejs rather than trusting this table if a runtime is rejected.

If a dependency is missing: state Not available in this environment, name the exact missing dependency, and provide the install command.

3) Ambiguity Resolution Gate

STOP and ASK if:

  • URL is not provided
  • Output directory is unspecified and matters (batch/playlist)
  • A stated constraint cannot be satisfied without a number (a storage cap, a target device, "must fit on X") — ask for the number
  • Playlist scope is ambiguous (full playlist vs single video from playlist URL)
  • Subtitle language is needed but not specified
  • Multiple URLs given without clear batch vs individual intent

Do not stop for vague quality wording. "Good quality", "high quality" and "best" all resolve to the default best-practical selector. Apply it, and state the assumption in the Output Contract's Inputs field: the user can correct one line of a delivered command far more cheaply than answering a question they did not think they had to answer. Ask only when a constraint makes the number load-bearing (see above).

4) Probe Gate

Do not guess format availability. Run a probe first when any of these apply:

ConditionProbe Command
Specific resolution/codec/format requestedyt-dlp -F "<url>"
Subtitle language availability unknownyt-dlp --list-subs "<url>"
Playlist scope unclear or very largeyt-dlp --flat-playlist --print "%(playlist_index)s %(title)s" "<url>"
URL may require auth or redirectyt-dlp --simulate --skip-download "<url>"
Site often changes formatsyt-dlp -F "<url>"

Skip the probe only for simple, public, single-video downloads where default best quality is acceptable.

5) Auth Safety Gate

  • Use cookies only for content the user is authorized to access
  • Prefer --cookies-from-browser <browser> over raw cookie files
  • Never ask the user to paste cookie contents into chat
  • Never describe cookies as a way to bypass paywalls or DRM
  • Never help circumvent geographic restrictions on copyrighted content
  • If auth is required but unavailable, stop at the command recommendation

6) Execution Mode Gate

Auto-select mode based on environment:

Signal→ Mode
Shell access available, yt-dlp installedFull
Shell available but yt-dlp missingBlocked (install first)
No shell access / sandbox environmentDegraded

7) Execution Integrity Gate

Never claim a download succeeded unless the command actually ran.

If executed: report final command, destination path, success/failure, key stderr/stdout summary. If not executed: report Not run in this environment, reason, exact command to run.

Defaults

Apply these unless the user requests otherwise:

--download-archive "<dir>/.yt-dlp-archive.txt"
--continue
--no-overwrites
--retries 10 --fragment-retries 10
-o "<dir>/%(title).200s [%(id)s].%(ext)s"

When logging is useful (batch, troubleshooting, unstable network), tee the output — but set pipefail first, or the shell reports tee's exit status and a failed download looks like a success, which contradicts the Execution Integrity Gate:

set -o pipefail
yt-dlp ... 2>&1 | tee "<dir>/yt-dlp.log"

If pipefail is unavailable (plain sh, some CI runners), use yt-dlp's own sink instead of a pipe: --print-to-file "%(filepath)s" "<dir>/yt-dlp.log" for paths, or simply redirect with > "<dir>/yt-dlp.log" 2>&1, which preserves the exit status.

Anti-Examples (Core Mistakes)

For the full set of 9 anti-examples, read references/anti-examples.md. The four most critical are inlined here (numbering is shared with the full catalog):

  1. Guessing format availability without probing — formats change per site and per video. Probe first.
    BAD:  yt-dlp -f 137+140 "<url>"  (assuming format IDs exist)
    GOOD: yt-dlp -F "<url>"  →  then pick from actual list
  2. Omitting --no-playlist for single-video watch URLs — YouTube watch URLs can trigger full playlist download.
    BAD:  yt-dlp -f "bv*+ba/b" "https://youtube.com/watch?v=xxx&list=yyy"
    GOOD: yt-dlp --no-playlist -f "bv*+ba/b" "https://youtube.com/watch?v=xxx&list=yyy"
  3. Claiming download success without running the command — if you did not execute it, say so.
  4. Re-starting from scratch when YouTube throttles mid-download — the .part file is preserved; re-run with --continue --limit-rate 2M --concurrent-fragments 1 to resume, not restart. See references/safety-and-recovery.md § YouTube throttling mid-download.

Honest Degradation

LevelConditionAction
Fullyt-dlp + ffmpeg available, shell access, command executedComplete execution report with all 7 output fields
DegradedNo shell access or sandbox environmentProvide recommended command + state assumptions + suggest probe command if confidence is low
Blockedyt-dlp not installed, or request involves DRM/unauthorized accessState the blocker + provide install command or explain why the request cannot proceed

Never report download success, file size, or format availability in Degraded or Blocked mode.

Safety Rules

  1. Never help download content the user is not authorized to access
  2. Never describe cookies as a DRM/paywall bypass method
  3. Never ask the user to paste cookie contents into chat
  4. Never claim a download ran unless it actually executed
  5. Never hardcode format IDs without probing the specific video
  6. Always include --no-playlist for single-video watch URLs with playlist parameters
  7. Always verify ffmpeg before merge/extract/embed operations
  8. Always pair --embed-subs with --write-subs (or --write-auto-subs) — --embed-subs alone does not download subtitles

Output Contract

Every response must include these 7 fields:

  1. Scenario — which template was selected
  2. Inputs — URL, output dir, format preference, subtitle needs, auth method
  3. Probe — probe command + results summary, or "skipped" with reason
  4. Final command — one complete, copy-pasteable command
  5. Execution status — ran successfully / failed (with key error) / not run (with reason)
  6. Output location — expected file path pattern
  7. Next step — corrective action if failed, or confirmation if succeeded

Load References Selectively

A simple public single-video request needs no reference file. The template below plus §Defaults is the whole command; loading more costs context and buys nothing:

yt-dlp --no-playlist -f "bv*+ba/b" --merge-output-format mp4 \
  --download-archive "<dir>/.yt-dlp-archive.txt" --continue --no-overwrites \
  --retries 10 --fragment-retries 10 \
  -o "<dir>/%(title).200s [%(id)s].%(ext)s" "<url>"

For any other scenario — playlist, audio, subtitles, auth, live, SponsorBlock, resolution or codec constraints: → Load references/scenario-templates.md for the complete templates (including 1b for a guaranteed-H.264/AAC MP4) to use as the base command.

When the output contract's shape is unclear, or the scenario is composite: → Load references/golden-examples.md for fully worked examples showing correct Scenario / Command / Defaults / Execution / Output fields per scenario type.

When choosing between format selectors, playlist modes, or subtitle strategies: → Load references/decision-rules.md for decision trees covering format selector priority (bv*+ba vs -f best), playlist scope flags, subtitle embedding vs external file, and archive file usage.

When the request specifies quality, codec, HDR, AV1, or specific resolution: → Load references/format-selection-guide.md for probe output interpretation, codec ranking tables, and HDR/AV1 selection flags.

When the user reports auth errors, extraction failures, or throttling, or when cookies or private content are involved: → Load references/safety-and-recovery.md for browser cookie extraction steps, retry flags, yt-dlp-ejs install guide, and throttling recovery patterns.

When reviewing or self-checking a generated command for common mistakes: → Load references/anti-examples.md for the remaining 5 of the 9 anti-examples (2, 4, 6, 7, 8) with corrected alternatives.

Bundled Assets

  • Contract tests: scripts/tests/test_skill_contract.py
  • Golden scenario tests: scripts/tests/test_golden_scenarios.py
  • Regression runner: scripts/run_regression.sh

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.