YouTube Archiver

Use this skill to import YouTube playlists into markdown files and optionally enrich notes with transcript, summary, and tagging.

Requirements

• Python 3.7+
• yt-dlp (pip install yt-dlp or brew install yt-dlp)
• A browser signed into YouTube (for private playlists like Liked/Watch Later)
• macOS: terminal needs Full Disk Access to read browser cookies
• Windows: browser cookie extraction can be flaky; cookies_file export is the safer path
• Linux: works on desktop installs; headless servers need cookies_file

First-run setup flow (interactive)

If no config exists at

/.config.json

, ask these questions before running scripts.

Required questions

1. Where should archived notes be stored?
• Default: ./YouTube-Archive
2. Which playlists should be archived?
• Accept playlist IDs or URLs
• Default: LL (Liked Videos), WL (Watch Later)
3. Which browser is signed into YouTube for cookie auth?
• Default: chrome

Optional enrichment questions

Ask only if the user wants summaries/tags.

1. Generate AI summaries? (yes/no)
2. Summary provider? (openai, gemini, anthropic, openrouter, ollama, none)
3. Summary model name?
4. API key env var name?
5. Enable auto-tagging? (yes/no)
6. Tagging provider/model/env var?
7. Keep default tags or define custom vocabulary?

First-run execution sequence

1. Run init:
• python3 /scripts/yt-import.py --output --init
2. Edit /.config.json from the user’s answers.
3. Verify auth with dry run:
• python3 /scripts/yt-import.py --output --dry-run
4. Run real import.
5. Run enrichment (optional):
• python3 /scripts/yt-enrich.py --output --limit 10

One-shot quick start

Use this for immediate manual sync:

python3 <skill>/scripts/yt-import.py --output <output-dir>
python3 <skill>/scripts/yt-enrich.py --output <output-dir> --limit 10

Useful import flags:

• --dry-run
• --playlist (repeatable)
• --no-summary
• --no-tags
• --cookies
• --browser

Useful enrich flags:

• --dry-run
• --limit
• --strict-config

Idempotency and safety behavior

• Import skips already archived videos by video_id.
• Filenames include video ID: Title [video_id].md.
• Enrichment skips notes where frontmatter has enriched: true.
• Lockfile prevents concurrent runs: /.yt-archiver.lock.

Automation with cron (single-agent default)

Offer cron only after one successful manual run.

Example schedule (daily 11:00):

1. Import new videos
2. Enrich a bounded batch

Example task text:

• Run yt-import.py for , then run yt-enrich.py --limit 10 for the same output.

Keep it single-agent by default. Do not assume multi-agent routing.

Troubleshooting and provider details

Read these references when needed:

• Provider setup, model suggestions, cost: references/providers.md
• Common failures and fixes: references/troubleshooting.md
• Default summary prompt template: references/default-summary-prompt.md