youtube-scout plugin

---
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 <topic>", 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: "<topic> [--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

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

```bash
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. |