yt-is

/yt-is — YouTube Channel Management

Check all tracked YouTube channels for new videos and manage your channel list.

Commands

• sync — Check all tracked channels for new videos
• sync --verbose — Show detailed output during check
• list — List all tracked channels with metadata
• add <url> — Add a new channel with full validation (YouTube Data API resolves @handle, rejects fake/empty/single-video channels, captures title/thumbnail/subscriber/view counts)
• history — Extract channels from YouTube watch history and add any new ones not already tracked. Filters: subscriber_count>100, video_count>2, most recent video within 3 months. Uses yt-dlp Python API + YouTube Data API + RSS feeds (no API quota for video IDs; RSS for recency).
  • ⚠️ Quota warning: history uses YouTube Data API for channel metadata resolution. Each channel lookup consumes API quota. If quota is exhausted, use history --dry-run to preview without adding.
  • history --dry-run — Preview channels without adding them
  • history --min-history-videos <n> — Minimum videos watched from a channel to qualify (default: 2)
• fetch — ESCALATION BATCH PROCESS: Download transcripts for all pending videos using the full fallback chain (RECOMMENDED)
  • fetch --dry-run — Preview what would be fetched
  • fetch --source <url> — Process only one channel
  • fetch --workers <n> — Use N parallel workers (default: 1)

/yt-is add — Channel Validation Workflow

When adding a channel, the system:

1. Resolves @handle via YouTube Data API (channels.list with contentDetails,statistics,snippet)
2. Rejects fake/empty channels — channels with ≤1 video are rejected (not stored)
3. Captures full metadata — channel_title, thumbnail_url, subscriber_count, view_count stored in channel_metadata
4. Enumerates all videos via API pagination and marks them as pending

The validation is strict — only channels with 2+ videos are accepted. This keeps the transcript corpus free of noise from abandoned or test channels.

Your Workflow

1. Parse the user's command (sync/list/add/fetch)
2. Run the appropriate csf-source backend command
3. MANDATORY — Copy and paste the output verbatim:
   • After the Bash command completes, copy the ENTIRE output text
   • Paste it directly in your response (inside a code block)
   • DO NOT summarize or abbreviate the output
   • DO NOT say "output shown above" or "the Bash tool result"
   • DO NOT reference the output indirectly — paste it literally
4. Why: The Bash tool output is compressed in the UI; pasting the raw text ensures the user can see it

Output Format

Paste the raw output from each command — the format is determined by the backend, not this skill. The backend output will include its own legend where applicable.

IMPORTANT: Bash output gets compressed in the UI. Always paste the raw output explicitly so the user can see it.

Your Tracked Channels

Run csf-source list to see current channel data. The backend output will include a legend explaining the column format.

How It Works

yt-is sync runs the daily check workflow on ALL tracked channels:

1. RSS Check - Fetches exactly 15 most recent videos per channel via RSS feed
2. Gap Detection - If RSS shows videos that don't exist in local database (no overlap), triggers gap resolution
3. API Gap Resolution - Uses YouTube Data API with publishedAfter cursor to fill gaps
4. Mark Pending - New videos are marked as pending for transcript download

Channels are checked in order of last_checked (oldest first) to ensure fair coverage.

Escalation Batch Process (csf-source fetch)

The fetch command implements automatic escalation for transcript downloading:

Escalation Chain (per video):

1. oEmbed reachability probe - Cheap early skip for removed/private videos
2. yt-dlp (WEB client) - Fastest method (~5 seconds), works for most public videos
3. yt-dlp with cookies - For age-restricted videos
4. direct API - Cheap terminal/no-transcript discriminator
5. NotebookLM Industrial - Best for backlog and clean transcripts
6. Selenium Firefox - Fallback for bot-check failures (~15-30 seconds)
7. Whisper - Audio fallback

Features:

• Automatic retries: Each video tries all methods until one succeeds
• Resume support: Interrupted runs skip already-cached videos
• Parallel processing: Use --workers N for concurrent downloads
• Status tracking: Automatically marks videos complete/failed in batch_status

Recommended Workflow:

# 1. Discover new videos
python bin/csf-source check-all

# 2. Download transcripts (all channels, automatic escalation)
python bin/csf-source fetch

# 3. Or dry-run first to see what will be fetched
python bin/csf-source fetch --dry-run

# 4. Or process only one channel
python bin/csf-source fetch --source "https://youtube.com/@channel"

# 5. Or use parallel workers for faster processing
python bin/csf-source fetch --workers 2

Data Flow

channel_metadata table (SQLite)
  │
  ├─► yt-is sync ──► RSS check ──► Gap detection ──► API resolution
  │                                                │
  │                                                ▼
  │                                       batch_status table (pending)
  │
  └─► python bin/csf-source fetch ──► FULL FALLBACK CHAIN ──► transcripts.sqlite

Storage

All data is stored in batch_status.sqlite:

• channel_metadata — tracked channels with playlist IDs and metadata
• analysis_status — video tracking (pending/complete/failed)

Files

• P://packages/yt-is/bin/yt-is — CLI entry point (wrapper)
• P://packages/yt-is/bin/csf-source — Backend implementation (YouTube source management CLI)
  • Prefer python bin/csf-source ... when launching from a shell inside the repo so you do not depend on PATH.
  • Rename note: If csf-source is renamed, update required_first_command_patterns (line 19) and all csf-source command references in this SKILL.md. Search for csf-source to find all occurrences.
• P://packages/yt-is/csf/source_enumerator.py — RSS + API enumeration
• P://packages/yt-is/csf/batch_status.py — SQLite storage

Requirements

• YOUTUBE_API_KEY — For gap resolution (API calls)
• Internet connection — For RSS feeds and YouTube Data API