Youtube idea finder

YouTube Idea Finder

Idea and name credit: inspired by Shane Hummus's YouTube videos on channel strategy and finding proven video ideas — this skill automates that "find videos overperforming their channel size" research.

Find videos on a given topic where the view count is large relative to the channel's subscriber count — a signal that a small or unknown creator produced something that broke out beyond their usual audience. This uses the YouTube Data API v3 (search.list, videos.list, channels.list) via a bundled script, so results are exact numbers straight from the API rather than scraped or estimated.

Inputs

The only thing the user is required to give you is the search term (the topic/niche). Everything else has a sensible default, and you should state the defaults you're using up front so the user can redirect you if they actually wanted something different:

Parameter	Default	Notes
Minimum views	100,000	The "overperformance" floor
Maximum subscribers	100,000	Keeps results to small/mid channels
Minimum views : subscribers ratio	5 : 1	The core "punching above their weight" signal
Number of candidates to find	5	Stop once you hit this many
Max search pages	5	Quota safety cap — see Quota below

If the user gives you different numbers, use theirs instead. If the script exhausts search results or hits the search-page cap before reaching the requested count, report however many qualifying videos it actually found — don't re-run with ever-looser queries trying to force a full set.

Getting an API key

If the user doesn't already have YOUTUBE_API_KEY set (see Tooling below), walk them through this rather than assuming they know it:

1. Go to the Google Cloud Console and create a project (or pick an existing one).
2. Enable the YouTube Data API v3 for that project.
3. Go to APIs & Services → Credentials → Create Credentials → API key.
4. Optionally restrict the key to the YouTube Data API v3 (recommended, but not required for this to work).

Google's own walkthrough covers this in more detail: Registering an application (YouTube Data API).

Cost: this is free. No billing account or credit card is required for the default quota — Google caps it at 10,000 quota units/day per project, which resets daily. A typical run of this skill (search + candidate lookups) costs roughly 200–550 units depending on how many search pages it needs (observed: ~510 units for a 5-page run), so the daily quota comfortably covers dozens of runs before you'd ever hit the cap.

Setting the key as an environment variable:

• macOS/Linux (zsh, the default on modern macOS): add it to ~/.zshenv (this file is sourced for every shell, including non-interactive ones that scripts run under, so it's more reliable here than ~/.zshrc):

  export YOUTUBE_API_KEY="your-key-here"
  

  Then open a new terminal, or run source ~/.zshenv in the current one.
• Windows: in PowerShell, run:

  setx YOUTUBE_API_KEY "your-key-here"
  

  setx persists it for future sessions but not the current one — close and reopen the terminal (or restart the app running Claude) before it takes effect. Alternatively, set it via System Properties → Environment Variables in the Windows GUI.

Tooling

This requires YOUTUBE_API_KEY to be set in the environment (see Getting an API key above) and the YouTube Data API v3 to be enabled for that key's Google Cloud project. If a call fails because the key is missing or invalid, or the key's quota is exhausted, the script reports this clearly on stderr with a non-zero exit — relay that message to the user rather than attempting a workaround (there is no scraping fallback anymore).

Run the script with Bash:

python3 ~/.claude/skills/youtube-idea-finder/scripts/youtube_idea_finder.py \
  --query "<search term>" \
  --min-views <N> --max-subs <N> --min-ratio <N> --count <N> --max-pages <N>

It prints one JSON object to stdout:

{
  "query": "...",
  "thresholds": {"min_views": ..., "max_subs": ..., "min_ratio": ..., "count": ...},
  "candidates": [
    {
      "title": "...", "video_id": "...", "url": "...",
      "views": 0, "channel_id": "...", "channel_title": "...",
      "subscribers": 0, "ratio": 0.0
    }
  ],
  "pages_searched": 0,
  "quota_used_estimate": 0,
  "stopped_reason": "reached_count | max_pages_reached | results_exhausted"
}

candidates is already filtered against all thresholds, Shorts-excluded, and sorted by ratio descending — you don't need to re-check the numbers, just format them (see Output format below).

Quota

search.list costs 100 quota units per page (50 results); videos.list and channels.list cost 1 unit per call regardless of batch size (up to 50 IDs batched per call). The default free quota is 10,000 units/day, so search pages are the only part worth budgeting — the script defaults to --max-pages 5 (≈500 units, ~510 observed in practice) so one run can't consume the whole daily quota. Mention quota_used_estimate from the result if the user seems to be running this repeatedly in a day, so they can judge how much headroom is left.

Raise --max-pages only if the user explicitly asks for a broader search or a larger --count than 5 pages is likely to satisfy — don't raise it speculatively.

Shorts handling

The API has no official "is this a Short" field. The script filters using contentDetails.duration: any video ≤3 minutes is treated as a Short and discarded before it ever reaches the candidate list, matching YouTube's own Shorts duration ceiling. This is a heuristic, not a certainty — if a result's legitimacy is in doubt (e.g. the user questions a specific result), you can spot-check by opening https://www.youtube.com/watch?v=<video_id> or noting the duration next to the title, but don't re-verify every candidate by default; the script already applied this filter to everything it returned.

Workflow

1. Post a quick overview before running the script

State the search term and the thresholds you'll apply (say plainly whether each is the default from the table above or a number the user gave you). Since a wrong assumption means re-running the search (and spending quota again), it's worth a beat to confirm before running.

2. Run the script

Invoke it via Bash with the query and thresholds. If it exits non-zero, relay the stderr message directly — don't retry blindly or invent a workaround.

3. Report the results

Take the candidates array from the JSON output and present it as the table below. If stopped_reason is "max_pages_reached" or "results_exhausted" and fewer candidates were found than requested, say so explicitly rather than silently returning a shorter list. If "max_pages_reached", mention that raising --max-pages (at the cost of more quota) could turn up more.

Output format

Report results as a markdown table, most-notable (highest ratio) first:

Title	Views	Subscribers	Channel	Ratio	Link
...	...	...	...	...:1	link

Briefly note any thresholds you used that weren't explicitly stated by the user, and if you stopped short of the requested count, say so plainly along with the reason (results_exhausted vs max_pages_reached).