tool-youtube

name

tool-youtube

description

Fetch latest videos from YouTube channels and extract full transcripts. Two modes: channel mode (list recent uploads, needs YOUTUBE_API_KEY) and transcript mode (get full timestamped transcript from a URL, free via yt-dlp). Chain both to get the latest video's full transcript from any channel. Triggers on: "latest youtube video", "get transcript", "youtube transcript", "what did they post", "fetch from youtube", "channel updates". Used by other skills (sci-communication, sci-trending-research) as a content source. Does NOT trigger for content creation, repurposing, or video editing.

YouTube Tool

Utility skill for getting content out of YouTube. Two scripts, two jobs:

• Channel mode — find out what someone posted recently, list their latest videos
• Transcript mode — pull the full text from a specific video

Chain them together: find the latest video from a channel, then pull its transcript. Other skills (like sci-communication and sci-trending-research) use this as a content source.

Outcome

YouTube video metadata and/or full transcripts saved to projects/tool-youtube/{video-title-slug}_{YYYY-MM-DD}.md. Always save output to disk. This is not optional.

Context Needs

None. This skill doesn't read brand context.

File	Load level	Purpose
context/learnings.md	## tool-youtube section	Known issues, channel quirks

Dependencies

None — this is a base utility. Other skills depend on this one.

Service	Key	Required For	Without It
YouTube Data API v3	YOUTUBE_API_KEY	Channel mode (listing videos, resolving @handles, search)	Can't list channel videos. Transcript mode still works if you have the URL.

Get a key at https://console.cloud.google.com/ (free tier is generous — 10,000 units/day).

Step 0: Auto-Setup (runs once)

Before doing anything else, check if the required binaries exist. If either is missing, run the setup script — it detects what's missing and installs it automatically.

bash .claude/skills/tool-youtube/scripts/setup.sh

This installs uv (for digest.py's inline dependencies) and yt-dlp (for transcript extraction). Uses brew on macOS, falls back to curl/pip otherwise. Only needs to run once per machine — skip on subsequent calls if both binaries exist.

Step 1: Determine the Request Type

Request	What to do
"Latest videos from [channel]"	Channel mode — use digest script (Step 2)
"Transcript of [URL]"	Transcript mode — use transcript script (Step 3)
"Latest video transcript from [channel]"	Chain both — Step 2 then Step 3
Another skill needs content	Provide the appropriate script output

Step 2: Channel Mode

Use the digest script to list recent uploads.

uv run .claude/skills/tool-youtube/scripts/digest.py --channels "@handle" --hours 48 --max-videos 5

This lists recent uploads with titles, dates, and URLs. Add --transcript to get a basic summary of each.

Needs: YOUTUBE_API_KEY in .env. If missing, tell the user what it does and how to get one. Don't block — ask them to provide a video URL directly as the fallback.

Script options:

Option	Default	What it does
--channels	—	Comma-separated @handles
--search	—	Comma-separated search queries
--hours	48	How far back to look
--max-videos	10	Cap on videos returned
--transcript	off	Include basic transcript summaries
--output	markdown	markdown or json
--seen-file	—	Track already-processed videos
--api-key	env var	Override YOUTUBE_API_KEY

Step 3: Transcript Mode

Use the transcript script for full text with timestamps.

python .claude/skills/tool-youtube/scripts/transcript.py "https://youtube.com/watch?v=VIDEO_ID" --output-dir /tmp

Then read the output file. No API key needed — yt-dlp handles it.

Script options:

Option	Default	What it does
--lang	en	Language code
--format	md	md (timestamped markdown) or vtt
--output-dir	.	Where to save the file
--auto-only	off	Only auto-generated subs
--list	—	List available subtitle tracks
--check-setup	—	Verify yt-dlp is installed

Step 4: Save Output

Always save the transcript to the projects folder. After extracting, create a clean version at projects/tool-youtube/{video-title-slug}_{YYYY-MM-DD}.md. The saved file format:

# {Video Title}

Source: {YouTube URL}
Channel: {channel name if known}
Date extracted: {YYYY-MM-DD}

## Key Points

- {3-5 most important points from the video}

## Transcript

{Full transcript text with all timestamps removed — clean readable paragraphs only}

Strip all **[HH:MM:SS]** timestamps from the raw transcript before saving. The saved file should read like a document, not a subtitle track. Create the folder if it doesn't exist.

Step 5: Collect Feedback

If used standalone, ask: "Got the transcript. Anything else you need from this video or channel?"

Log feedback to context/learnings.md → ## tool-youtube.

---

Rules

Updated automatically when the user flags issues. Read before every run.

---

Self-Update

If the user flags an issue — wrong channel, bad transcript, missing data — update the ## Rules section immediately with the correction and today's date.

---

Troubleshooting

• Setup script fails: If brew isn't available, the script falls back to curl (for uv) and pip (for yt-dlp). If both fail, tell the user to install manually.
• No API key: Channel listing won't work. Transcript mode still works with direct URLs. Tell the user how to get a key and offer the URL fallback.
• yt-dlp not installed: Run bash .claude/skills/tool-youtube/scripts/setup.sh — it auto-installs. If that fails, brew install yt-dlp manually.
• No transcripts available: Some videos don't have captions. The script will say so. Suggest the user paste a transcript manually.
• Channel not found: The @handle might be wrong, or the channel might be very new. Try searching by name instead of handle.