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