Youtube video evaluator

YouTube Idea Evaluator

Takes video candidates (usually from youtube-idea-finder) and produces an actionable diagnostic report per video: what its thumbnail and editing actually look like and why, what topics/tech/format it covers, and a concrete "replicate this, fix that, do this for your own calendar" brief.

This skill does not search YouTube or apply any pass/fail filter — every candidate handed to it gets a full write-up. The point isn't to find gaps to exploit, it's to reverse-engineer what worked (and what didn't) well enough to turn it into a content calendar entry.

Do not modify youtube-idea-finder. It stays a standalone skill. This skill only consumes its output (or a manually supplied list of video IDs/URLs).

Inputs

• A JSON output file from youtube_idea_finder.py (has a candidates array with video_id per entry), or
• A plain list of YouTube video IDs or URLs the user pastes in directly

If the user hasn't run the finder yet and asks for both in one request, run the finder first, show its table, then feed its candidates into this skill. The finder needs a search term/niche to run — if the user hasn't given one (e.g. they just said "find me some video ideas and evaluate them"), ask for it before invoking the finder. Don't guess a query on their behalf.

If a --finder-json file is supplied instead (e.g. from an earlier session, or handed off without restating the query in this conversation), read the search term for the output filename directly from that file's top-level query field rather than relying on conversation context — youtube_idea_finder.py always writes it there.

Scope

• In scope: thumbnail quality, editing/pacing quality, topics covered, tech/tools named, format/framing, and what's replicable vs. what needs fixing.
• Out of scope: audio quality (no way to assess it reliably without actually listening, so don't guess at it or even flag it as unassessed, just leave it out entirely). Captions are also out of scope — nearly every candidate tested turns out to lack them, which makes it a non-differentiating, arbitrary check rather than a real signal; don't fetch, check, or mention captions anywhere in the workflow or report. Don't gate or rank candidates into skip/green-light tiers — every candidate gets the full write-up regardless of how good or bad its packaging is, since the goal is proven-demand topics to build a calendar from, not a shortlist of "easy wins."

Workflow

1. Fetch metadata and thumbnails

Batch-fetch all candidates in one call with the bundled script (mirrors youtube_idea_finder.py's own API usage, same YOUTUBE_API_KEY env var):

python3 ~/.claude/skills/youtube-video-evaluator/scripts/fetch_video_metadata.py \
  --finder-json /path/to/finder_output.json \
  --out-dir /path/to/scratch/dir

Or with explicit IDs: --ids ID1,ID2,ID3 instead of --finder-json.

This returns title, full description, tags, duration, view/like/comment counts, and downloads each video's best-available thumbnail to <out-dir>/thumbnails/<id>.jpg. Read each thumbnail file directly to view it (you have vision) — never re-fetch thumbnails by hand with curl, and never try to embed the image bytes into any deliverable (base64-encoding images for a document or widget is slow and produces a bad experience; describe what you see in words instead). Ignore the has_captions field in its output — captions are out of scope (see Scope above).

2. Judge each thumbnail

Rate Bad / Mediocre / Good against:

• Bad: plain screen recording or default frame, generic stock imagery, a wall of text with no focal point, no face or a face that blends in, low contrast or hard-to-read fonts, no clear promise in 2 seconds
• Good: bold text with one clear hook word, a face with an expressive reaction (or, if no face, a visual that shows the payoff directly — e.g. a before/after icon metaphor, or an actual screenshot of the working output), high contrast, the payoff is obvious at a glance
• Mediocre: has a real hook or decent contrast but is missing the other elements, or executes the idea half-heartedly (e.g. legible but cluttered, or a clear hook let down by a weak visual)

Note why in one line, specific enough that the user knows exactly what to avoid or copy, not just the label.

3. Judge editing quality from storyboard frames at 0s/45s/90s

Do not use claude-in-chrome or any browser-based playback for this step — an earlier version of this skill relied on screenshotting the live <video> element and repeatedly produced false "frozen cold open" findings because the tab's video stream silently failed to buffer any real data (readyState stuck at 0, buffered empty) while still rendering a static poster frame. That failure mode is indistinguishable from a real frozen video in a screenshot, so it went undetected until caught and verified against an independent source. Storyboards sidestep the problem entirely: they're static sprite-sheet images YouTube generates for its own scrub-bar preview, fetched over plain HTTP with no player and no playback state to go wrong.

Fetch frames with the bundled script (requires yt-dlp — brew install yt-dlp if missing — and ffmpeg, mirrors the metadata script's conventions):

python3 ~/.claude/skills/youtube-video-evaluator/scripts/fetch_storyboard_frames.py \
  --url https://www.youtube.com/watch?v=VIDEO_ID \
  --checkpoints 0,45,90 \
  --out-dir /path/to/scratch/dir/storyboards/VIDEO_ID

This prints a JSON summary listing each checkpoint's actual sampled time (storyboard sampling is roughly 1 frame per 1.5-2s, so it rarely lands on the exact requested second) and the path to a cropped JPEG per checkpoint. Read each cropped JPEG directly to view it. If a video has no storyboard formats at all (rare), the script exits with a clear error — fall back to describing editing quality as unassessed for that one video rather than guessing, and say so in the report.

Rate Bad / Mediocre / Good against:

• Bad: the checkpoints show no real progression (same or near-identical frame at 0s/45s/90s, consistent with a genuinely static title card that long), full OS/browser chrome visible on a screen recording, rambling structure with no hook visible at 0s
• Good: clearly distinct content at each checkpoint showing real structural variety (e.g. talking head to screen-share, cuts to a diagram/B-roll, demo-first hook already visible at 0s), clean cropped capture
• Mediocre: real progression exists between checkpoints but composition is weak (e.g. raw uncropped screen recording with no zooms or host-cam presence), or a strong cold open that isn't sustained by the later checkpoints

Three sample points can't catch individual cuts or confirm exact pacing — they establish gross content-type and macro-pacing (static vs. changing, talking-head vs. screen-share vs. diagram), which is enough signal for this rating. Don't claim a specific duration for a static stretch (e.g. "static for the first 90 seconds") beyond what the sampled checkpoints actually show — if 0s is static but 45s already shows real content, say the static stretch ended sometime before 45s, not that it lasted 90 seconds.

4. Extract topics, tech/tools, and format

• Topics: pull from the description's chapter list when present, or from the video's own narrative structure if not
• Tech/tools: pull from API tags plus anything named on-screen or in the description (specific frameworks, libraries, platforms)
• Format: name the shape, not just "tutorial" — e.g. single-concept explainer, head-to-head comparison, hands-on build (basic/advanced), talking-head roadmap, whiteboard system-design walkthrough, news-jacking reaction to a recent release. The format is often what actually explains the view-to-subscriber ratio, more than production polish does — a short single-concept explainer or a comparison riding a trending keyword can outperform a narrower, better-produced project build by an order of magnitude. Say so when the pattern shows up.

5. Write the per-video brief

For every candidate, regardless of rating:

• What to replicate: specific, nameable techniques — title formulas, thumbnail construction, structural beats (agenda slides, demo-first hooks, branded stings, PiP webcam styling), even on videos with mediocre or bad packaging (the topic itself still proved demand, that's always replicable even when the execution isn't)
• What to fix: concrete weaknesses, specific enough to act on. Don't let a "Good" rating suppress this section — call out real gaps even on well-produced videos
• Calendar action: one line translating the above into a concrete next step sized for a content calendar entry

Output format

A single Markdown file, filename Video Ideas - [search terms].md (note the plural "Ideas"), saved in the user's current working directory unless told otherwise. If evaluating a manually supplied list of IDs/URLs with truly no query field to recover it from (see Inputs above), ask the user what to name the file — don't ask if the term was recoverable from a supplied finder JSON.

Before writing, check whether the resolved filename already exists in the target directory. If it does, append (1), (2), etc. before the .md extension (Video Ideas - [search terms] (1).md, then (2), ...) and use the first one that doesn't collide. Never overwrite an existing report and never prompt the user to confirm an overwrite — this applies regardless of whether the search term came from the user, from a finder JSON's query field, or from asking the user directly.

Structure:

# Video Ideas - [search terms]

| # | Title | Channel | Ratio | Format |
|---|---|---|---|---|
| 1 | [Title](url) | Channel | N.NN:1 | Format label |
...

---

## 1. [Title]

| Field | Detail |
|---|---|
| Channel | ... |
| Link | ... |
| Views / Subscribers / Ratio | ... |
| Format | ... |
| Topics | ... |
| Tech/tools | ... |
| Thumbnail | **Good/Mediocre/Bad.** One-line specific reason. |
| Editing | **Good/Mediocre/Bad.** One-line specific reason. |

**What to replicate:**
- ...

**What to fix:**
- ...

**Calendar action:** One line.

---

## 2. [Title]
...

Always bold the Good/Mediocre/Bad rating at the start of the Thumbnail and Editing table cells — the prose reasoning alone reads as ambiguous without it. Use a proper two-column table for each video's metadata block, not a stack of bold key:value lines — loose lines with single newlines collapse onto one line in rendered Markdown and become unreadable.

Default to the Markdown file as the deliverable. Only reach for a visual card/widget presentation if the user explicitly asks for one — it's a heavier, slower artifact and real images can't be embedded in it without a costly base64 round-trip, so it ends up carrying less information than the plain Markdown version anyway.

If the finder returns fewer candidates than requested

Not this skill's problem to solve, but worth relaying: state plainly how many were evaluated vs. requested and why (max_pages_reached vs. results_exhausted, from the finder's own output), same as the finder skill itself would.