Skill

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).

Invocation

How this skill is triggered — by the user, by Claude, or both

Slash command

/manage-youtube:manage-youtube

User invocable

Model invocable

Inline context

Default effort

Context Preview

The summary Claude sees in its skill listing — used to decide when to auto-load this skill

> **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.

Supporting Files

SKILL.md

921 lines · ~6.6k tokens(exceeds 5k compaction limit)

Stats

LanguageTypeScript

Parent stars0

MaintenanceExcellent

Last CommitMay 9, 2026

Actions

View Source View Plugin View on GitHub View README

Stats

Actions

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

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

Content Discovery Tools (No Authentication)

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

Local Organization Tools (No Authentication)

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

Playlist Management Tools (OAuth Required)

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

Shared Libraries (Not CLI Tools)

Library	Purpose
`youtube-client.ts`	Shared client for content discovery tools
`video-library-client.ts`	Shared client for video organization

Tool characteristics:

Content discovery tools accept channel handles (@username), URLs, or channel IDs
All tools support --json flag for structured output
All tools support --help flag for usage information
Print status messages to stderr, data to stdout
Playlist tools require one-time OAuth authentication </prebuilt_tools>

**Get channel info (basic)**: ```bash npx tsx channel-info.ts --channel "@GoogleDevelopers" ```

Get 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):

Handle: @GoogleDevelopers
Plain handle: GoogleDevelopers
URL: https://www.youtube.com/@GoogleDevelopers
Channel ID: UC_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 ID
channelHandle - The channel's @handle
channelName - The channel's display name

Options 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:

Full URL: https://www.youtube.com/watch?v=dQw4w9WgXcQ
Short URL: https://youtu.be/dQw4w9WgXcQ
Embed URL: https://www.youtube.com/embed/dQw4w9WgXcQ
Shorts URL: https://www.youtube.com/shorts/abc123
Video ID: dQw4w9WgXcQ </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:

Channel ID, handle, name
Subscriber count, video count (if --resolve used)
Description snippet, thumbnail URL
Date added to favorites </favorites_management>

<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:

Deleting a topic removes it from videos (videos retain other topics)
Deleting a thematic makes its topics uncategorized
Videos are never automatically deleted

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:

Linked to saved videos (stored in video's reportPath field)
Standalone reports (not linked to any saved video)

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:

Tokens: ~/.google-skills/youtube/youtube-tokens.json
Cache: ~/.google-skills/youtube/playlists-cache.json

API 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:

Content Discovery Tool Errors

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

Playlist Tool Errors (Official API)

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:

Content discovery tools: No built-in rate limiting. Add delays for bulk operations.
Playlist tools: Automatic retry with exponential backoff for transient errors. Daily quota limit applies. </error_handling>

<anti_patterns>

Never run bulk operations without delays - YouTube may temporarily block rapid requests
Never expect all videos to have transcripts - Some videos have no captions
Never hardcode video/channel IDs - Accept as parameters
Never ignore the --json flag for scripting - Human-readable output is harder to parse </anti_patterns>

<success_criteria> A successful YouTube operation:

Returns valid JSON when --json flag is used
Prints [OK] status messages to stderr
Exit code 0 for success, 1 for errors
Handles all supported URL/ID formats </success_criteria>

<detailed_references> For complete implementation details and library documentation, see:

SETUP-CREDENTIALS.md - First-time credentials setup for playlist management
references/youtube-guide.md - Full YouTube monitoring guide
references/implementation-notes.md - Implementation details and troubleshooting
references/video-organization.md - Video organization feature design and details
references/playlist-tools.md - Official YouTube API playlist management guide </detailed_references>

manage-youtube

Invocation

Context Preview

Supporting Files

SKILL.md

manage-youtube

Invocation

Context Preview

Supporting Files

SKILL.md

Content Discovery Tools (No Authentication)

Local Organization Tools (No Authentication)

Playlist Management Tools (OAuth Required)

Shared Libraries (Not CLI Tools)

Content Discovery Tool Errors

Playlist Tool Errors (Official API)

Similar Skills

Content Discovery Tools (No Authentication)

Local Organization Tools (No Authentication)

Playlist Management Tools (OAuth Required)

Shared Libraries (Not CLI Tools)

Content Discovery Tool Errors

Playlist Tool Errors (Official API)

Similar Skills