scout

# /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 (defaul...