/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
| Flag | Default | Meaning |
|---|
--max N | 50 | Videos to collect, 1 to 200. Each block of 50 uses one of the 100 daily search calls. |
--since | any | hour, today, week, month, year, any |
--length | any | short (under 4 min), medium (4 to 20), long (over 20) |
--sort | views | views, engagement, likes, recent, momentum (views per day), breakout (views per subscriber) |
--comments [N] | off | Top N comments per video (default 20) into a Comments sheet, plus Top Comment on each video row. 1 quota unit per video. |
--hooks [SECONDS] | off | yt-dlp probe per video, no quota: Hook (first SECONDS of captions, default 15), Vertical, FPS, Most Replayed s, Replay Hotspots, Chapters, and a Transcripts sheet with the full transcript. |
--out PATH | ./scout-<topic>-<date>.xlsx | Write a new workbook |
--into PATH | off | Append into an existing workbook's Videos sheet, skip Video IDs already present, re-sort. Comments and Transcripts sheets are created or extended there too. A timestamped .backup- copy is written next to the file first. The file must be closed in Excel. |
--download [N] | off | Save thumbnails for every video (Thumbnail File) and mp4s for the top N (Local File) into ./downloads/; all videos when N is omitted. Full downloads can be slow, so prefer a small N. |
--transcribe [MODEL] | off | Transcribe audio locally with Whisper for every video that has no caption transcript (default model turbo, GPU recommended). Uses the downloaded mp4 or fetches audio only. Fills Hook, Transcript Words, Transcript Source, and the Transcripts sheet. No quota, no caption requests. |
--dry-run | off | Fetch and print only |
--json | off | Also print rows as JSON |
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
| Code | Meaning | What to tell the user |
|---|
| 0 | success | relay the report |
| 1 | usage error | fix the flags and rerun |
| 2 | no API key | export YOUTUBE_API_KEY, or put it in ~/.config/scout/.env, or point SCOUT_ENV_FILE at the key file |
| 3 | quota exhausted | the 100 daily searches or 10,000 daily units are used up; they reset at midnight Pacific |
| 4 | invalid API key | check the YOUTUBE_API_KEY value in the key file |
| 5 | other API or network error | show the message, suggest retry |
| 6 | file error | the --into file is missing or openpyxl is not installed |
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.