Yt Thumbnail Brief

---
name: yt-thumbnail-brief
description: Turn a YouTube video idea into a designer-ready thumbnail brief: focal subject, face and emotion, a text overlay of 4 words or fewer that the title does not repeat, contrast and composition, and 2 to 3 A/B concepts for Test and Compare. Built on 2026 principles (one focal point, legible at 120 pixels, complements the title). Outputs the brief plus the Publora attach step (the image upload itself is out of band). Use to plan a thumbnail. Not for title words (use yt-title-optimizer).
---

# YouTube Thumbnail Brief

This skill does not generate an image. It writes the brief a human designer (or
an image tool) executes, grounded in what actually drives the click in 2026, and
documents how a custom thumbnail gets attached when you auto-publish.

## When to use

- User says "what should the thumbnail be for this video"
- User wants a brief to hand to a designer or paste into an image generator
- User wants 2 to 3 thumbnail concepts to A/B test
- User is auto-publishing and needs the thumbnail upload steps

## What the brief contains

For each concept the skill outputs:

- **Concept name and the angle** it sells (and how it complements the title).
- **Focal subject:** a face plus the specific emotion, or the object/result.
- **Text overlay:** the exact words (4 or fewer), and where they sit. Never the
  same words as the title.
- **Background and contrast:** color, lighting, and how the subject separates.
- **Composition:** rule-of-thirds placement, gaze direction, crop.
- **120-pixel test note:** what must still read when shrunk to mobile size.

## Steps

1. **Gather inputs.** The title (so the thumbnail complements, never repeats it),
   the video's payoff and emotional tone, whether there is a face available, the
   single most visual moment or result, and long-form vs Short. If a URL is
   given, parse it with `lib/url_parser.py`.
2. **Split the load with the title.** Decide what the title already says and make
   the thumbnail carry the rest (the face/emotion, the result, the object). List
   the split explicitly.
3. **Write 2 to 3 concepts.** Vary one big element between them (face vs object,
   text vs no text, color), not five small things, so the A/B test is readable.
   Each concept fills the six fields above.
4. **Apply the non-negotiables.** One focal point, a legible real emotion, high
   contrast, 4 words or fewer of text, and it must read at 120 px. Flag any
   concept that risks failing the shrink test.
5. **Recommend the lead concept** for YouTube's Test & Compare and say why.
6. **Hand off the brief.** The user gives it to a designer or an image tool. This
   skill writes words, not pixels.
7. **If auto-publishing, give the upload flow** (see below). Otherwise the user
   sets the thumbnail in YouTube Studio.

## The thumbnail flow (auto-publish)

A custom thumbnail cannot be set on `create-post` because the thumbnail upload
needs a `postGroupId` first. The order is:

1. Create the video post as a **draft** (`create-post`, no scheduledTime) ->
   returns the `postGroupId`.
2. **Upload the thumbnail image out of band.** Publora requires the thumbnail to
   be a tracked media asset from its dedicated YouTube thumbnail endpoint (JPEG
   or PNG, max 2 MB, 1280x720 recommended). That upload is **not wired into this
   bundle**: do it in the Publora dashboard (or via the dedicated endpoint once
   available). The generic `get-upload-url` media flow is not accepted for
   thumbnails. The upload returns a `mediaId` and `url`.
3. Attach it: call `update-post` with
   `platformSettings.youtube.thumbnail = {mediaId, url}` (the
   `lib.PubloraClient.set_thumbnail(post_group_id, media_id=, url=)` helper wraps
   this attach step). This is the part the bundle automates.
4. Schedule the post.

So this skill outputs the thumbnail **brief plus the attach instructions**, not a
one-call thumbnail upload. If you do not have a tracked `{mediaId, url}` yet, ship
the video without the custom thumbnail and set it in YouTube Studio.

Constraints: the channel must be **verified**; the apply is **best-effort** (a
rejected thumbnail does not block the video, it just ships without the custom
one); and you cannot change the thumbnail while the post is `processing`.

## Hard rules

Global voice rules: see root `SKILL.md` Voice rules. Additional skill-specific
rules:

- Text overlay is 4 words or fewer, and never repeats the title's words.
- One focal point per concept. Two competing subjects halve the click.
- The emotion on a face must match the video. A shocked face on a calm tutorial
  is a broken promise the retention graph punishes.
- Every concept must pass the 120-pixel mobile read test.
- Always produce 2 to 3 concepts, each varying one big element.

## Anti-patterns (skill will refuse)

- Repeating the full title as the thumbnail text.
- A face with a fake exaggerated expression that the video does not earn.
- A busy collage with no single focal point.
- Tiny text or full sentences that vanish at 120 px.
- A thumbnail showing a moment that is not in the video.
- Em dashes in any overlay text.

## Resources

- `../../references/thumbnail-principles.md` - the full design language and the upload flow
- `../../references/algorithm-heuristics.md` - packaging, CTR, Test & Compare
- `references/brief-template.md` - the fill-in brief a designer or image tool can execute

## Related skills

- `yt-title-optimizer` - the other half of the click; build them as a pair
- `yt-hook-scripter` - the spoken open should match the thumbnail's emotion
- `yt-content-planner` - pair titles and thumbnails across a week