From manage-youtube
Search, discover, consume, and manage YouTube content using TypeScript CLI tools. Use when the user asks to search YouTube, get channel information, retrieve videos from a channel, get video transcripts, analyze YouTube content, manage favorite channels, organize saved videos with topics and thematics, or manage YouTube playlists (list, create, update, delete, add/remove videos). Works with channel handles (@username), URLs, or channel IDs. Includes both third-party API tools (no auth required) and official YouTube API tools (OAuth required for playlist management).
npx claudepluginhub weirdapps/integrations-marketplace --plugin manage-youtubeThis skill uses the workspace's default tool permissions.
> **Path Convention**: All paths in this document are relative to this skill's root directory. When executing commands, first `cd` to the skill directory or adjust paths accordingly.
SETUP-CREDENTIALS.mdreferences/implementation-notes.mdreferences/playlist-tools.mdreferences/video-organization.mdreferences/youtube-guide.mdtools/channel-info.tstools/channel-search.tstools/channel-videos.tstools/favorites.tstools/package.jsontools/playlist-auth.tstools/playlist-manage.tstools/playlist-sync.tstools/playlist-tools/cli/auth.tstools/playlist-tools/cli/playlists.tstools/playlist-tools/cli/sync.tstools/playlist-tools/package.jsontools/playlist-tools/src/api/playlist-items.tstools/playlist-tools/src/api/playlists.tstools/playlist-tools/src/auth/oauth-client.tsCreates isolated Git worktrees for feature branches with prioritized directory selection, gitignore safety checks, auto project setup for Node/Python/Rust/Go, and baseline verification.
Executes implementation plans in current session by dispatching fresh subagents per independent task, with two-stage reviews: spec compliance then code quality.
Dispatches parallel agents to independently tackle 2+ tasks like separate test failures or subsystems without shared state or dependencies.
Enable Claude Code to interact with YouTube programmatically using prebuilt TypeScript CLI tools. This skill provides:Path Convention: All paths in this document are relative to this skill's root directory. When executing commands, first
cdto the skill directory or adjust paths accordingly.
Content Discovery (third-party libraries, no auth required):
Video Organization (local storage):
Playlist Management (official YouTube API, OAuth required):
Data storage: ~/.google-skills/youtube/
favorite-channels.json - Stored favorite channels listsaved-videos.json - Saved videos with topics and thematicsreports/ - Video content reports (markdown files)reports/index.json - Reports index and metadataYouTubeSkill-Credentials.json - OAuth credentials (for playlist tools)youtube-tokens.json - OAuth tokens (auto-created by playlist tools)playlists-cache.json - Local playlist cache (auto-created by playlist tools)Setup for Content Discovery Tools (no auth required):
cd ./tools
npm install
Setup for Playlist Management Tools (OAuth required):
# Install dependencies
cd ./tools/playlist-tools
npm install
# Authenticate with YouTube (opens browser)
npx tsx ./tools/playlist-auth.ts login
Two Types of Tools:
| Category | Authentication | Write Access | Quota Limits |
|---|---|---|---|
| Content Discovery (channel-*, search, transcript, etc.) | None | No | Informal |
| Playlist Management (playlist-*) | OAuth 2.0 | Yes | 10,000 units/day |
Libraries used:
youtubei.js - Full YouTube access via InnerTube API (content discovery)youtube-sr - Lightweight search fallback (content discovery)youtube-caption-extractor - Transcript extraction (content discovery)googleapis - Official Google API client (playlist management)
<quick_start> Get channel information:
npx tsx ./tools/channel-info.ts \
--channel "@GoogleDevelopers" --json
Get recent videos from a channel:
npx tsx ./tools/channel-videos.ts \
--channel "@GoogleDevelopers" --limit 5 --json
Get recent videos from multiple channels:
npx tsx ./tools/channel-videos.ts \
--channels "@GoogleDevelopers,@indydevdan,@matthew_berman" --limit 3 --json
Search YouTube:
npx tsx ./tools/search.ts \
--query "typescript tutorial 2025" --limit 10 --json
Get video transcript:
npx tsx ./tools/transcript.ts \
--video "dQw4w9WgXcQ" --text-only
Get video details:
npx tsx ./tools/video-details.ts \
--video "https://www.youtube.com/watch?v=dQw4w9WgXcQ" --json
Manage favorite channels:
# Add channels to favorites
npx tsx ./tools/favorites.ts \
--action add --channels "@GoogleDevelopers,@freeCodeCamp" --resolve
# List favorites
npx tsx ./tools/favorites.ts --action list --json
Manage YouTube playlists (requires OAuth):
# Authenticate first (one-time)
npx tsx ./tools/playlist-auth.ts login
# List all your playlists
npx tsx ./tools/playlist-manage.ts list --json
# Create a new playlist
npx tsx ./tools/playlist-manage.ts create \
--title "My Learning Path" --privacy private
# Add video to playlist
npx tsx ./tools/playlist-manage.ts \
add-video PLxxxxxxxx dQw4w9WgXcQ
# Sync all playlists locally
npx tsx ./tools/playlist-sync.ts all
</quick_start>
<prebuilt_tools>
Location: ./tools/
| Tool | Purpose |
|---|---|
channel-info.ts | Get channel metadata (name, subscribers, description) |
channel-videos.ts | Get videos from channel (recent, by date, popular) |
channel-search.ts | Search for videos within a specific channel |
search.ts | Search YouTube globally with filters |
transcript.ts | Get video captions/transcript |
video-details.ts | Get detailed video info and related videos |
| Tool | Purpose |
|---|---|
favorites.ts | Manage favorite channels list (add, remove, list) |
saved-videos.ts | Save and organize videos with topics |
video-topics.ts | Manage topics (labels) for video organization |
video-thematics.ts | Manage thematics (groups of topics) |
video-reports.ts | Create and manage video content reports |
| Tool | Purpose |
|---|---|
playlist-auth.ts | OAuth authentication for YouTube API (login, logout, status) |
playlist-manage.ts | Full CRUD on playlists and playlist items |
playlist-sync.ts | Local caching, sync, and diff operations |
| Library | Purpose |
|---|---|
youtube-client.ts | Shared client for content discovery tools |
video-library-client.ts | Shared client for video organization |
Tool characteristics:
--json flag for structured output--help flag for usage informationGet channel info (detailed with About tab data):
npx tsx channel-info.ts --channel "UC_x5XG1OV2P6uZZ5FSM9Ttw" --detailed --json
Channel identifier formats (all work for any tool):
@GoogleDevelopersGoogleDevelopershttps://www.youtube.com/@GoogleDevelopersUC_x5XG1OV2P6uZZ5FSM9Ttw
</channel_operations><video_retrieval> Get N most recent videos from a single channel:
npx tsx channel-videos.ts --channel "@GoogleDevelopers" --limit 10 --json
Get videos from multiple channels (aggregated, sorted by date):
npx tsx channel-videos.ts --channels "@GoogleDevelopers,@indydevdan,@matthew_berman" --limit 5 --json
Get videos from last N days:
npx tsx channel-videos.ts --channel "@GoogleDevelopers" --after-days 7 --json
Get videos from last N days across multiple channels:
npx tsx channel-videos.ts --channels "@channel1,@channel2" --after-days 7 --json
Get N most popular videos:
npx tsx channel-videos.ts --channel "@GoogleDevelopers" --popular 5 --json
Get N most popular videos across multiple channels:
npx tsx channel-videos.ts --channels "@channel1,@channel2" --popular 10 --json
Search within a channel:
npx tsx channel-search.ts --channel "@GoogleDevelopers" --query "kubernetes" --limit 10 --json
Multi-channel output includes channel info:
When using --channels, each video includes:
channelId - The channel's YouTube IDchannelHandle - The channel's @handlechannelName - The channel's display nameOptions for channel-videos.ts:
| Flag | Description |
|---|---|
--channel <id> | Single channel (handle, URL, or ID) |
--channels <list> | Comma-separated list of channels |
--limit <N> | Videos per channel (default: 10) |
--after-days <N> | Only videos from last N days |
--popular <N> | Get N most popular by views |
--sort-by-date | Sort by date (auto-enabled for multi-channel) |
--json | Output as JSON |
| </video_retrieval> |
<search_operations> Basic search:
npx tsx search.ts --query "react tutorial" --limit 10 --json
Search with filters:
npx tsx search.ts --query "python course" \
--upload-date week \
--duration long \
--sort view_count \
--limit 20 --json
Search filter options:
--type: video, channel, playlist--upload-date: hour, today, week, month, year--duration: short (<4min), medium (4-20min), long (>20min)--sort: relevance, upload_date, view_count, rating
</search_operations><transcript_operations> Get transcript as plain text:
npx tsx transcript.ts --video "dQw4w9WgXcQ" --text-only
Get transcript with timestamps:
npx tsx transcript.ts --video "dQw4w9WgXcQ" --with-timestamps
Get transcript with video details:
npx tsx transcript.ts --video "dQw4w9WgXcQ" --with-details --json
Search transcript for keywords:
npx tsx transcript.ts --video "dQw4w9WgXcQ" --search "never,gonna,give" --json
Specify language:
npx tsx transcript.ts --video "dQw4w9WgXcQ" --lang es --text-only
</transcript_operations>
<video_details> Get video details:
npx tsx video-details.ts --video "dQw4w9WgXcQ" --json
Get video details with related videos:
npx tsx video-details.ts --video "dQw4w9WgXcQ" --related 5 --json
Video URL formats supported:
https://www.youtube.com/watch?v=dQw4w9WgXcQhttps://youtu.be/dQw4w9WgXcQhttps://www.youtube.com/embed/dQw4w9WgXcQhttps://www.youtube.com/shorts/abc123dQw4w9WgXcQ
</video_details><favorites_management> List all favorite channels:
npx tsx favorites.ts --action list --json
Add channels to favorites (supports multiple, comma-separated):
# Basic add (just resolves IDs)
npx tsx favorites.ts --action add --channels "@GoogleDevelopers,@freeCodeCamp"
# Add with full info (fetches metadata)
npx tsx favorites.ts --action add --channels "@GoogleDevelopers,fireship" --resolve
Remove channels from favorites (supports multiple):
npx tsx favorites.ts --action remove --channels "@GoogleDevelopers,freeCodeCamp"
Get a specific favorite channel:
npx tsx favorites.ts --action get --channel "@GoogleDevelopers" --json
Clear all favorites:
npx tsx favorites.ts --action clear
Favorites data location: ~/.google-skills/youtube/favorite-channels.json
Stored data per channel:
<video_organization> Video Organization Hierarchy:
Thematic (broad category, e.g., "AI & Machine Learning")
├── Topic (label, e.g., "LangChain Tutorials")
│ ├── Video A
│ └── Video B
└── Topic (label, e.g., "Prompt Engineering")
└── Video C
Uncategorized Topics (topics without thematic)
└── Topic (e.g., "Watch Later")
└── Video D
Uncategorized Videos (videos without topics)
└── Video E
Create thematics and topics:
# Create a thematic (broad category)
npx tsx video-thematics.ts add "AI & Machine Learning" \
--description "Videos about AI/ML concepts"
# Create topics within a thematic
npx tsx video-topics.ts add "LangChain" --thematic "AI & Machine Learning"
npx tsx video-topics.ts add "Claude/Anthropic" --thematic "AI & Machine Learning"
# Create an uncategorized topic
npx tsx video-topics.ts add "Watch Later"
Save videos with topics:
# Save video with topic and priority (--resolve fetches metadata)
npx tsx saved-videos.ts add "https://youtu.be/abc123" \
--topic "LangChain" \
--notes "Great tutorial on LCEL" \
--priority 1 \
--resolve
# Save uncategorized video
npx tsx saved-videos.ts add "xyz789" --resolve
# Add multiple topics to existing video
npx tsx saved-videos.ts update abc123 \
--add-topic "Claude/Anthropic" \
--add-topic "Prompt Engineering"
Browse and filter videos:
# List all videos sorted by priority
npx tsx saved-videos.ts list --sort priority
# List videos in a specific topic
npx tsx saved-videos.ts list --topic "LangChain"
# List all videos in a thematic
npx tsx saved-videos.ts list --thematic "AI & Machine Learning"
# List uncategorized videos
npx tsx saved-videos.ts list --unassigned
# Search videos by keyword
npx tsx saved-videos.ts search "tutorial"
Manage organization structure:
# List thematics with topics and counts
npx tsx video-thematics.ts list --with-topics --with-counts
# List all topics with video counts
npx tsx video-topics.ts list --with-counts
# Move topic to different thematic
npx tsx video-topics.ts move "LangChain" --thematic "Web Development"
# Move topic to uncategorized (omit --thematic)
npx tsx video-topics.ts move "LangChain"
# Rename a topic
npx tsx video-topics.ts rename "LangChain" --name "LangChain Framework"
# Get detailed view of a thematic
npx tsx video-thematics.ts get "AI & Machine Learning" --with-topics --with-videos --json
Cascade behavior on delete:
Video data location: ~/.google-skills/youtube/saved-videos.json
Stored data per video (when using --resolve):
| Category | Fields |
|---|---|
| Core | Video ID, title, URL, date added |
| Channel | Channel ID, name, handle (@username) |
| Content | Description, duration (text & seconds), published date, category, keywords, isShort |
| Engagement | Views (text & count), likes (text & count) |
| Media | Thumbnail URL |
| User | Topic assignments, personal notes, metadata (priority, extensible), report path |
| </video_organization> |
<video_reports> Reports Management
Reports are detailed content analyses stored as markdown files. They can be:
reportPath field)Reports storage: ~/.google-skills/youtube/reports/
Create a report for a video:
# Create report from a file and link to saved video
npx tsx video-reports.ts create "Video Analysis Report" report.md \
--video "zuJyJP517Uw" --link
# Create from stdin
cat report.md | npx tsx video-reports.ts create "My Report" - --video "abc123" --link
Create a standalone report (not linked to any video):
npx tsx video-reports.ts create "Research Notes" notes.md
List all reports:
npx tsx video-reports.ts list --json
Get report metadata or content:
# Get metadata by video ID
npx tsx video-reports.ts get "zuJyJP517Uw" --json
# Get actual report content
npx tsx video-reports.ts get "zuJyJP517Uw" --content
Link/unlink reports:
# Link existing report to a saved video
npx tsx video-reports.ts link "report-filename.md" "zuJyJP517Uw"
# Unlink report from video
npx tsx video-reports.ts unlink "zuJyJP517Uw"
Remove a report:
npx tsx video-reports.ts remove "zuJyJP517Uw"
</video_reports>
<playlist_management> YouTube Playlist Management (OAuth Required)
These tools use the official YouTube Data API v3 and require OAuth authentication.
First-Time Setup:
# Install playlist-tools dependencies (one-time)
cd ./tools/playlist-tools
npm install
# Authenticate with YouTube (opens browser)
npx tsx ./tools/playlist-auth.ts login
Authentication Operations:
# Check authentication status
npx tsx playlist-auth.ts status
# Refresh access token
npx tsx playlist-auth.ts refresh
# Logout (remove tokens)
npx tsx playlist-auth.ts logout
# Show storage file paths
npx tsx playlist-auth.ts paths
Playlist CRUD Operations:
# List all your playlists
npx tsx playlist-manage.ts list
npx tsx playlist-manage.ts list --json
# Get specific playlist details
npx tsx playlist-manage.ts get PLxxxxxxxxxxxxxxxx --json
# Create a new playlist
npx tsx playlist-manage.ts create --title "My Playlist" --privacy private
npx tsx playlist-manage.ts create --title "Public List" --description "Description" --privacy public
# Update playlist
npx tsx playlist-manage.ts update PLxxxxxxxx --title "New Title"
npx tsx playlist-manage.ts update PLxxxxxxxx --privacy unlisted
npx tsx playlist-manage.ts update PLxxxxxxxx --description "New description"
# Delete playlist (requires confirmation)
npx tsx playlist-manage.ts delete PLxxxxxxxx --confirm
Playlist Item Operations:
# List videos in a playlist
npx tsx playlist-manage.ts videos PLxxxxxxxx
npx tsx playlist-manage.ts videos PLxxxxxxxx --json
# Add video to playlist (supports video ID or URL)
npx tsx playlist-manage.ts add-video PLxxxxxxxx dQw4w9WgXcQ
npx tsx playlist-manage.ts add-video PLxxxxxxxx https://youtube.com/watch?v=dQw4w9WgXcQ
npx tsx playlist-manage.ts add-video PLxxxxxxxx dQw4w9WgXcQ --position 0
# Remove video from playlist (uses playlist item ID, not video ID)
# First get the item ID from 'videos' command
npx tsx playlist-manage.ts remove-video PLxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Sync and Cache Operations:
# Sync all playlists to local cache
npx tsx playlist-sync.ts all
npx tsx playlist-sync.ts all --verbose
# Sync specific playlist
npx tsx playlist-sync.ts playlist PLxxxxxxxx
# View cache status
npx tsx playlist-sync.ts status
# View cached playlists (offline)
npx tsx playlist-sync.ts local
npx tsx playlist-sync.ts local --json
npx tsx playlist-sync.ts local PLxxxxxxxx
# Compare local cache with YouTube
npx tsx playlist-sync.ts diff
npx tsx playlist-sync.ts diff --json
# Compare videos in a specific playlist
npx tsx playlist-sync.ts diff-items PLxxxxxxxx
# Clear local cache
npx tsx playlist-sync.ts clear --confirm
Privacy Options: public, private, unlisted
Data locations:
~/.google-skills/youtube/youtube-tokens.json~/.google-skills/youtube/playlists-cache.jsonAPI Quota: Operations cost 1-50 units. Daily limit is 10,000 units. </playlist_management>
<common_patterns> Get latest video and transcribe it:
# Get most recent video
VIDEO=$(npx tsx channel-videos.ts --channel "@GoogleDevelopers" --limit 1 --json | jq -r '.[0].id')
# Get its transcript
npx tsx transcript.ts --video "$VIDEO" --with-details --json
Search and analyze results:
# Search for videos
npx tsx search.ts --query "AI coding assistant" --upload-date week --limit 5 --json > results.json
# Process each video for transcripts
cat results.json | jq -r '.[].id' | while read vid; do
npx tsx transcript.ts --video "$vid" --text-only > "transcript_$vid.txt"
done
Monitor channel for new content:
# Get videos from last 24 hours
npx tsx channel-videos.ts --channel "@GoogleDevelopers" --after-days 1 --json
Get recent videos from all favorite channels:
# Method 1: Use --channels with favorites list (recommended - single call, sorted by date)
HANDLES=$(npx tsx favorites.ts --action list --json | jq -r '.channels[].handle' | tr '\n' ',' | sed 's/,$//')
npx tsx channel-videos.ts --channels "$HANDLES" --limit 3 --json
# Method 2: Loop through each channel separately
npx tsx favorites.ts --action list --json | jq -r '.channels[].handle' | while read handle; do
echo "=== Videos from $handle ==="
npx tsx channel-videos.ts --channel "$handle" --limit 3 --json
done
Add multiple channels from a file:
# channels.txt contains one handle per line
cat channels.txt | tr '\n' ',' | xargs -I {} npx tsx favorites.ts --action add --channels "{}" --resolve
Save video while watching and organize later:
# Quick save without topic
npx tsx saved-videos.ts add "dQw4w9WgXcQ" --resolve
# Later, assign topics
npx tsx saved-videos.ts update "dQw4w9WgXcQ" \
--add-topic "Music" \
--notes "Classic!"
Build a curated learning playlist by priority:
# Create structure
npx tsx video-thematics.ts add "Learning Path"
npx tsx video-topics.ts add "Week 1" --thematic "Learning Path"
npx tsx video-topics.ts add "Week 2" --thematic "Learning Path"
# Add videos with priority
npx tsx saved-videos.ts add "video1" --topic "Week 1" --priority 1 --resolve
npx tsx saved-videos.ts add "video2" --topic "Week 1" --priority 2 --resolve
# List in order
npx tsx saved-videos.ts list --topic "Week 1" --sort priority
Get high-priority unwatched videos:
npx tsx saved-videos.ts list --sort priority --json | jq '.[:5]'
Filter videos by engagement (using JSON output):
# Get most viewed saved videos (using viewCount for accurate sorting)
npx tsx saved-videos.ts list --json | jq 'sort_by(.viewCount) | reverse | .[:10]'
# Find long-form videos (over 20 minutes)
npx tsx saved-videos.ts list --json | jq '[.[] | select(.durationSeconds > 1200)]'
# Find YouTube Shorts
npx tsx saved-videos.ts list --json | jq '[.[] | select(.isShort == true)]'
# Get videos by category
npx tsx saved-videos.ts list --json | jq '[.[] | select(.category == "Education")]'
Use keywords for discovery:
# Find videos with specific keywords
npx tsx saved-videos.ts list --json | jq '[.[] | select(.keywords | any(. == "tutorial"))]'
Backup all YouTube playlists locally:
# Authenticate if not already done
npx tsx playlist-auth.ts status || npx tsx playlist-auth.ts login
# Sync all playlists with full details
npx tsx playlist-sync.ts all --verbose
# Export to JSON file
npx tsx playlist-manage.ts list --json > ~/my-youtube-playlists.json
Create a YouTube playlist from local saved videos:
# Create the playlist on YouTube
npx tsx playlist-manage.ts create --title "From Saved Videos" --privacy private
# Get the playlist ID and add videos from a topic
PLAYLIST_ID="PLxxxxxxxx"
npx tsx saved-videos.ts list --topic "Watch Later" --json | jq -r '.[].videoId' | while read vid; do
npx tsx playlist-manage.ts add-video "$PLAYLIST_ID" "$vid"
done
Detect and report playlist changes:
# First sync to establish baseline
npx tsx playlist-sync.ts all
# Later, check for changes
npx tsx playlist-sync.ts diff --json
# Get detailed changes for specific playlist
npx tsx playlist-sync.ts diff-items PLxxxxxxxx --json
Import videos from YouTube playlist to local organization:
# Get videos from a YouTube playlist and save locally
npx tsx playlist-manage.ts videos PLxxxxxxxx --json | jq -r '.[].videoId' | while read vid; do
npx tsx saved-videos.ts add "$vid" --topic "Imported from YouTube" --resolve
done
Migrate playlist to different privacy setting:
# Make a private playlist public
npx tsx playlist-manage.ts update PLxxxxxxxx --privacy public
# Or make it unlisted (accessible only via link)
npx tsx playlist-manage.ts update PLxxxxxxxx --privacy unlisted
</common_patterns>
<error_handling> Common errors and solutions:
| Error | Cause | Solution |
|---|---|---|
| Could not resolve channel handle | Invalid handle or channel doesn't exist | Verify the handle/URL is correct |
| Failed to fetch transcript | No captions available | Not all videos have captions |
| InnerTube search failed | Rate limiting or API changes | Tool auto-falls back to youtube-sr |
| Client not initialized | Internal error | Report issue, retry |
| Error | Cause | Solution |
|---|---|---|
| AUTH_REQUIRED | Not authenticated | Run playlist-auth.ts login |
| AUTH_EXPIRED | Access token expired | Run playlist-auth.ts refresh or login |
| QUOTA_EXCEEDED | API quota exceeded | Wait 24 hours or request quota increase |
| PLAYLIST_NOT_FOUND | Invalid playlist ID | Verify playlist exists and ID is correct |
| VIDEO_NOT_FOUND | Invalid video ID | Verify video exists and ID format is valid |
| PERMISSION_DENIED | Not your playlist | Can only modify your own playlists |
| Invalid playlist ID | ID format wrong | Playlist IDs start with PL, UU, LL, WL, etc. |
| Invalid video ID | ID format wrong | Video IDs are exactly 11 characters |
Rate limiting:
<anti_patterns>
<success_criteria> A successful YouTube operation:
--json flag is used[OK] status messages to stderr<detailed_references> For complete implementation details and library documentation, see: