thumbnail-brief

---
name: thumbnail-brief
description: Turns a finished video into three build-ready thumbnail or first-frame briefs, each with a receipt of where the video pays the promise off. Use before publishing.
---

# A thumbnail people click without feeling tricked

Three variants a designer can build today, with proof each claim is kept in the video.

## Claude does

1. Ask for five inputs, invent none: transcript with timestamps, the payoff moment and its timestamp, destination surface, whether a real face or frame exists, brand hex codes. No timestamps, no job.
2. Surface first. Feed video: the first frame is the thumbnail, since Jenny Hoyos reports 99.9% of Shorts views come from the feed, so design frame 0 at 1080x1920 as three agreeing tracks (spoken line, on-screen text, opening visual). Browse: 1280x720.
3. Write the promise ledger first: one claim per row with the timestamp that delivers it. MrBeast's internal handbook makes the opening prove the thumbnail's promise. No timestamp means the claim is cut, not softened into the same lie.
4. Assume silence and a small tile: of 5,616 US adults surveyed by Verizon Media and Publicis Media, 80% said captions make them likelier to finish a video, half watch muted. Text is 3 to 5 words and reads shrunk to a browse tile.
5. Use Hoyos's power words (banned, free, one dollar, secret, cheap) only where literally true. Ban leverage, delve, harness, "hey guys", and adjectives where a number exists: "3 takes", not "a few takes".
6. Three variants, three mechanisms, not three colourways: each with hex codes, composition, focal point and its ledger rows.
7. Treat "faces lift CTR 20-30%" as untested, since claude-youtube states it uncited: test it in one variant.

## Then Codex does

Codex does the mechanical half: pulling frames at the ledger timestamps, expanding each spec into a build sheet of layers, pixel positions and font sizes, writing alt text and filenames, opening the A/B log.

Fill in first: {VARIANT_SPECS}, {PROMISE_LEDGER}, {VIDEO_PATH}, {BRAND_HEX}, {SURFACE}.

```
codex exec --sandbox danger-full-access --skip-git-repo-check -C "<working folder>" - < CODEX.md
```

## Claude checks

1. Every claim sits in the ledger with a timestamp found in the transcript.
2. No file restates the 20-30% face figure, or any borrowed number, as fact.
3. The frames exist. A missing PNG is a failure, not a pass.
4. Feed video got frame 0, browse got 1280x720, not the reverse.
5. Text is 3 to 5 words, legible muted at tile size, unchanged from the spec.

Reject and rerun: name the failing check, rerun CODEX.md. Never patch by hand, never soften a claim.

## Rules

- A claim without a timestamp is cut, not reworded.
- The surface decides the canvas.
- Borrowed benchmarks are hypotheses to test, not evidence.
- Public information only.
- Never invent a fact, a number or a quote.
- Anything sent in someone's name says whose name it is.

## If Codex is not installed

Claude builds the sheets, alt text and log itself and says so.

## Built from

- AgriciDaniel/claude-youtube, https://github.com/AgriciDaniel/claude-youtube, 350 stars (api.github.com, 5 Sep 2026).
- Jenny Hoyos with Shorts lead Todd Sherman, https://blog.youtube/creator-and-artist-stories/youtube-shorts-deep-dive/ (YouTube's blog).
- MrBeast internal handbook, https://simonwillison.net/2024/Sep/15/how-to-succeed-in-mrbeast-production/.
- Verizon Media and Publicis Media, https://www.3playmedia.com/blog/verizon-media-and-publicis-media-find-viewers-want-captions/, 5,616 US adults.
- sergebulaev/tiktok-skills, https://github.com/sergebulaev/tiktok-skills, 22 stars (api.github.com, 5 Sep 2026).

# Thumbnail build sheets - Codex task

## You are given

- {VARIANT_SPECS}: three approved thumbnail briefs (A, B, C). Each names a mechanism, the exact on-screen text, hex codes, composition and focal point.
- {PROMISE_LEDGER}: rows of `claim | timestamp`. Every claim that appears on a thumbnail is delivered at that timestamp in the video.
- {VIDEO_PATH}: absolute path to the source video file.
- {BRAND_HEX}: the permitted colour list.
- {SURFACE}: `feed` (canvas 1080x1920, frame 0 of a Shorts, TikTok or Reels video) or `browse` (canvas 1280x720, YouTube search and browse).

## Produce

1. `thumbnails/frames/` - one PNG per ledger timestamp, extracted with `ffmpeg -ss <timestamp> -i <video> -frames:v 1`. Name each `frame-<timestamp>.png`.
2. `briefs/variant-a.md`, `variant-b.md`, `variant-c.md` - for each: the canvas size from {SURFACE}; a layer list top to bottom, every layer with x,y in pixels, width, height, font size in pixels, hex and opacity; the on-screen text copied verbatim; the ledger rows the variant depends on; the candidate frame filename.
3. `thumbnails/alt-text.txt` - one line per variant, plain description of what is visible, no claim that is absent from {PROMISE_LEDGER}.
4. `thumbnails/ab-log.csv` - header `variant,surface,mechanism,text,published_at,impressions,ctr,avg_view_duration,verdict`; three rows filled as far as `text`, the rest blank.
5. `thumbnails/CHECK.md` - a table of claim, timestamp, variants using it, and the frame file for that timestamp.

## Rules

- Copy every piece of text verbatim. Never rewrite, shorten or improve wording.
- Never add a claim, number, statistic or quote that is not in {PROMISE_LEDGER}. Public information only.
- Use only colours in {BRAND_HEX}.
- Banned words: leverage, delve, harness, hey guys, unlock, game-changer. No em dash characters. British English.
- If a ledger row has no timestamp, or a timestamp is past the end of the video, stop and report it. Do not pick a frame yourself.
- Keep all text inside a centred safe area, and state the exact top, bottom, left and right margins you used so they can be checked against a live platform preview. Platform interface overlays differ per app and per format.
- Any file written to be sent or published in a person's name must state whose name it goes out in.

## Return

Print, in this order: every file written with its byte size; the three variants' on-screen text exactly as written; any ledger row missing a timestamp; the ffmpeg exit code per frame; the four margin values used; the canvas size used. If anything stopped you, print `BLOCKED: <reason>` and write no partial files.