YouTube Search Skill

Search YouTube and return structured video results as JSON.

Usage

Run the search script with a query:

node ./scripts/search.mjs "your search query"

Options

Examples

# Basic search
node scripts/search.mjs "typescript tutorial"

# Limit results
node scripts/search.mjs "bun runtime" --max-results=5

# Filter by upload date
node scripts/search.mjs "claude code" --upload-date=month

# Combine filters
node scripts/search.mjs "react tutorial" --max-results=5 --upload-date=week --duration=long

Output Format

The script outputs a JSON array to stdout. Each element has:

[
  {
    "videoId": "dQw4w9WgXcQ",
    "title": "Video title",
    "channel": {
      "name": "Channel Name",
      "id": "UCxxxxxx",
      "url": "https://www.youtube.com/channel/UCxxxxxx"
    },
    "duration": "3:32",
    "viewCount": "1,234,567 views",
    "publishedTime": "2 days ago",
    "publishedDate": "2026-02-18",
    "description": "Short snippet of the video description...",
    "thumbnail": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  }
]

Rendering Results

Always present results as a markdown table with the video title rendered as a clickable link. Use this format:

How It Works

1. Fetches the YouTube search results page for the given query
2. Extracts the embedded ytInitialData JSON from the HTML response
3. Parses video renderers from the search result contents
4. Returns structured JSON to stdout

No YouTube API key is required. The script scrapes public YouTube search pages using the same technique a browser would use.

Error Handling

• Errors are written to stderr so they don't interfere with JSON output on stdout
• Non-zero exit code on failure
• Gracefully handles missing fields in video data (returns null for unavailable fields)