name: scout description: Scout a topic on YouTube. Searches YouTube Data API v3 for the most relevant videos, ranks them by views (or engagement, likes, recency, momentum, breakout), and writes a research workbook in the OWT-Social-Ads layout with Videos, Channels, and Summary sheets, plus optional Comments and Transcripts (hooks, replay hotspots) sheets. Can also append into an existing sheet. Use when the user says "scout ", wants a spreadsheet of top YouTube videos on a topic, wants creator or hook research, or wants YouTube rows added to their social ads sheet. argument-hint: " [--max 50] [--since month] [--length short] [--sort views] [--comments] [--hooks] [--transcribe] [--into file.xlsx] [--download [N]] [--dry-run]" allowed-tools: Bash, Read user-invocable: true

/scout

One topic in, one ranked research workbook out. The script does the whole job; your role is to run it with the right flags, then relay the result.

Step 1: Run

python3 "${CLAUDE_SKILL_DIR}/scripts/scout.py" <topic words> [flags]

Pass the user's topic as words after the script (quotes optional, the script joins them). The API key is read from YOUTUBE_API_KEY in the environment, then from the file named by SCOUT_ENV_FILE, then ~/.config/scout/.env, then ./.env. If the user keeps keys in another env file, load it into the environment first (for example set -a; . <keyfile>; set +a in the same Bash call) rather than copying the key anywhere. Never echo the key. The run prints progress lines to stderr; a full run with --hooks on 50 videos takes a few minutes because yt-dlp probes each video, so allow a long Bash timeout.

If the script reports that openpyxl is missing, run once:

pip install -r "${CLAUDE_SKILL_DIR}/requirements.txt" --quiet

Flags

Mapping user phrasing: "this month" means --since month, "shorts" means --length short, "what are people saying" or "objections" means --comments, "hooks", "scripts", "openers", "transcripts" or "most replayed" means --hooks, "creators to reach out to" means look at the Channels sheet, "add to my sheet" means --into <that file>. "Everything" or "full research" means --comments --hooks. When the user names no file and no flags, use the defaults.

Step 2: Report

The script prints a top-10 table to stdout and status lines to stderr. Relay:

• The output path and the sheet list (or rows added and skipped for --into).
• The top-10 table as-is in a code block.
• Quota used (search calls out of 100 a day, units out of 10,000 a day), and any warning: lines (a few yt-dlp probe failures are normal).
• Two or three observations worth acting on, read from the Summary sheet and the table: for example the Shorts share, a breakout creator (high Views/Sub), or a recurring hook pattern.

Mention once, when relevant, that Shares, Spark Code, Sheet Views, and Ad Status stay blank for YouTube rows: YouTube's API exposes no share count, and the other three are manual columns in the user's sheet. Engagement % for YouTube rows is (likes + comments) / views. Click-through rate, retention, impressions, and demographics are not available for other people's videos; the replay heatmap from --hooks is the closest public proxy for retention.

Exit codes

Sheet layout

Videos: the base columns follow OWT-Social-Ads.xlsx (Platform, Creator, Handle, Video ID, Video Link, Posted as Unix epoch, Views, Likes, Comments, Shares, Engagement %, Duration s, Spark Code, Local File, Sheet Views, Ad Status). In a new workbook, columns that would be blank on every row are left out (Shares, Spark Code, Sheet Views, Ad Status always; Local File and Thumbnail File without --download; the comment and hook columns without their flags). In --into mode the full layout is kept so it lines up with the existing sheet. Then:

• Performance: Title, Published, Relevance # (position in YouTube's relevance results), Format (Short, Video, Live), Age d, Views/day, Views/Sub, Like %, Comment %.
• Channel: Channel URL, Subscribers, Channel Videos, Channel Views, Avg Views/Video, Channel Country, Channel Created, Channel Keywords, Channel Topics.
• Metadata: Category, Tags, Tag Count, Language, Captions, HD, Licensed, Embeddable, Made for Kids, Paid Promotion (creator-declared), AI Disclosure (creator-declared synthetic media), License, Live, Topics, Blocked Regions, Description (first 300 chars), Desc Links, Location, Thumbnail.
• With --comments: Top Comment, Top Comment Likes, Comments Off.
• With --hooks: Hook, Vertical, FPS, Most Replayed s, Replay Hotspots (true peaks of the "most replayed" curve, the opening decay is ignored), Chapters, Transcript Words. Format is corrected to Video when a short clip turns out to be horizontal. Hook and Transcript stay blank when a video has no captions at all, and the replay columns stay blank when YouTube has not published a heatmap for it (it needs enough views), so partial coverage is normal.

--hooks caches every yt-dlp probe and caption under ~/.cache/scout/ for 7 days, so a rerun of the same topic (or a --into run on the same videos) only fetches what is missing. YouTube rate-limits caption downloads after bursts (HTTP 429); the script paces fetches 1.5 s apart and retries with backoff, and if some still fail it prints one warning with the count. Tell the user the block is per IP and can last hours: add --transcribe to fill the gaps locally, or rerun later. SCOUT_CAPTION_DELAY, SCOUT_CACHE_DIR, and SCOUT_DOWNLOAD_FORMAT override the pacing, cache location, and download format (default: 480p video and audio streams merged into mp4). For "cover every column" or a full demo, use --comments --hooks --transcribe --download 10.

Usually blank, kept for the rare hit: AI Disclosure (YouTube only returns it in some cases), Live, Blocked Regions, Location, Paid Promotion. Tags are blank when the creator added none.

• With --hooks or --transcribe: Transcript Source says captions or whisper per row.
• With --download [N]: Thumbnail File for every row, Local File (column N) for the top N.

Channels: one row per channel in the sample, sorted by sample views: handle, subscribers, channel totals, country, created, videos in sample, sample views, sample average engagement, best video and link, keywords, topics. This is the creator outreach list.

Summary: topic, run date, filters, quota, totals, median and mean views, average engagement, median duration, Shorts share, paid promotion share, captions share, published range, top video, top channels, top tags, categories, languages, channel countries.

Comments (flag): Video ID, Handle, Title, Author, Comment, Likes, Replies, Published, link.

Transcripts (flag): Video ID, Handle, Title, Language, Source, Transcript Words, Hook, full Transcript (capped at 32,000 characters), link.

Header styling, frozen header, autofilter, number formats, and hyperlinks are reproduced on every sheet. New workbooks only get Channels and Summary; --into leaves those out because aggregates over a mixed sheet would mislead.

youtube-scout

One topic in, one ranked YouTube research workbook out. Type /scout matcha recipe in Claude Code and get an .xlsx with the most relevant videos ranked by performance, the creators behind them, what the audience says in the comments, the opening lines that hooked viewers, and the moments people replay.

Not affiliated with, sponsored by, or endorsed by YouTube or Google. YouTube and Google product names are trademarks of their owners.

Why youtube-scout

• Everything the public API exposes, in one sheet. 48 columns per video: views, likes, comments, engagement, views per day, views per subscriber, format, category, tags, language, captions, paid promotion flag, channel size and country, and more. No field left on the table.
• Signals you cannot get from the YouTube UI. Breakout ratio (views per subscriber), momentum (views per day), the top comment per video, hook text from captions, and replay hotspots from the "most replayed" curve, the closest public proxy for retention.
• Fits an existing research sheet. The first columns match a social ads tracking layout, so --into your-sheet.xlsx appends YouTube rows next to TikTok and Instagram rows, dedups by video id, re-sorts, and keeps your manual columns and hyperlinks intact.

What you get

Installation

No GitHub account is needed to install.

Manual install (Unix, macOS, Linux)

git clone https://github.com/AgriciDaniel/youtube-scout.git
cd youtube-scout
./install.sh            # copies the skill to ~/.claude/skills/scout
python3 -m pip install --user openpyxl
python3 -m pip install --user yt-dlp    # optional, for --hooks, --download, and --transcribe

./install.sh --target codex, --target agents, --target portable, or --target all install to other agent runtimes. ./uninstall.sh removes it.

Plugin install (Claude Code)

/plugin marketplace add AgriciDaniel/youtube-scout
/plugin install youtube-scout@agricidaniel-youtube-scout

API key

Create a YouTube Data API v3 key in Google Cloud Console, restrict it to that API, then either export it or put it in a key file:

export YOUTUBE_API_KEY=...            # for the session
# or
mkdir -p ~/.config/scout && chmod 700 ~/.config/scout
printf 'YOUTUBE_API_KEY=...\n' > ~/.config/scout/.env && chmod 600 ~/.config/scout/.env

SCOUT_ENV_FILE=/path/to/keys.env points the skill at any other env file.

Quick start

/scout matcha recipe
/scout iced matcha latte --since month --length short --max 100
/scout ai seo --comments --hooks
/scout ai seo --comments --hooks --transcribe --download 10
/scout matcha recipe --into OWT-Social-Ads.xlsx
/scout matcha recipe --sort breakout --dry-run

Each run prints a top-10 table and writes scout-<topic>-<date>.xlsx in the current folder.

Flags

Sample output

/scout ai seo, 50 videos, one search call:

 #        Views   Eng %     V/day   V/Sub      Len  Fmt   Handle               Title
 1      544,925    2.37     1,048     0.8     7:26  Video ahrefscom            SEO in 2025: How I'd Learn it if I Were Starting O
 2      374,587    1.51       612    83.4     0:08  Short webhivedigital       Best SEO Tools For 2025 #SEO #SEOtools #googlerank
 3      205,208    2.97     1,387     6.1    50:46  Video surferseo            The Complete SEO & AI SEO Course for 2026 (Full Be
 4      149,955    3.29       318     4.5    18:10  Video surferseo            How to Dominate AI Search Results in 2026 (ChatGPT
 5      134,896    2.30       219     0.7    28:27  Video levelingupofficial   RIP SEO: Here's What Works Now in an AI World

The Summary sheet for that run reported 14% Shorts, a median length of 12 minutes, and a creator with 4,490 subscribers whose 8-second Short reached 375,000 views (views per subscriber 83). Those are the rows worth studying.

Architecture

topic
  |  search.list (relevance, paginated, 1 of 100 daily search calls per 50)
  v
video ids
  |  videos.list (snippet, statistics, contentDetails, status, topicDetails,
  |               recordingDetails, paidProductPlacementDetails, liveStreamingDetails)
  |  channels.list (snippet, statistics, topicDetails, brandingSettings)
  |  videoCategories.list
  v
rows  --sort-->  Videos / Channels / Summary sheets
  |  --comments: commentThreads.list per video (1 unit each)
  |  --hooks:    yt-dlp -j per video, json3 captions, heatmap peaks (no quota, cached)
  |  --transcribe: local Whisper on the downloaded file or fetched audio (no quota, cached)
  v
scout-<topic>-<date>.xlsx   or   --into existing.xlsx

Engagement % is (likes + comments) / views. Views per day uses the video age with a floor of six hours. Format is Short when a video is 180 seconds or less and not confirmed horizontal.

Quota and limits

• Since June 2026 the API uses granular quota buckets: 100 search.list calls a day, plus 10,000 units a day for everything else. A default 50-video run uses 1 search call and 3 units; adding --comments adds 1 unit per video. The run prints what it used.
• YouTube blocks caption downloads per IP after bursts (HTTP 429), and the block can last several hours. The skill paces requests, retries with backoff, caches probes under ~/.cache/scout/ for 7 days, and stops trying after one hard failure. --transcribe fills the gaps by transcribing the audio locally with Whisper, which never touches the caption endpoint. The Transcript Source column says which rows came from captions and which from Whisper.
• Full video downloads can be slow when YouTube throttles them. --download 10 saves mp4s for the top 10 only, plus thumbnails for every row.
• yt-dlp breaks whenever YouTube changes something. yt-dlp -U usually fixes it within a day. Metadata columns still fill when captions fail.

Limitations

• Shares, click-through rate, impressions, retention, and demographics are not available for other people's videos through any API. The replay heatmap is the closest public proxy.
• AI Disclosure is in the API documentation but is rarely returned for public videos.
• Search relevance is not deterministic; two runs of the same topic can differ by a few videos.
• Append mode rewrites the Videos sheet body. Charts or images on that sheet would not survive. A timestamped backup is written first, and the file must be closed in Excel.

FAQ

Does it need OAuth? No. An API key is enough for everything the skill reads.

Can I use it on my own channel's analytics? No. Retention and traffic sources live in YouTube Analytics, which is a diffe