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
- 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. - 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.
- 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.
- 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.
- Recommend the lead concept for YouTube's Test & Compare and say why.
- Hand off the brief. The user gives it to a designer or an image tool. This skill writes words, not pixels.
- 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:
- Create the video post as a draft (
create-post, no scheduledTime) -> returns thepostGroupId. - 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-urlmedia flow is not accepted for thumbnails. The upload returns amediaIdandurl. - Attach it: call
update-postwithplatformSettings.youtube.thumbnail = {mediaId, url}(thelib.PubloraClient.set_thumbnail(post_group_id, media_id=, url=)helper wraps this attach step). This is the part the bundle automates. - 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.
- Punctuation in overlay text, em dashes included (a 3-word overlay is read at thumbnail size; it carries words, not clauses).
Resources
../../references/thumbnail-principles.md- the full design language and the upload flow../../references/algorithm-heuristics.md- packaging, CTR, Test & Comparereferences/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 pairyt-hook-scripter- the spoken open should match the thumbnail's emotionyt-content-planner- pair titles and thumbnails across a week