CommunityImagegithub.com

ai-thumbnail

Shows an agent how to direct or produce "ai thumbnail" so the concrete output is usable copy or a script. The procedure moves through AI-channel thumbnail, Setting a person up, once, When all you have is a video still. Use it when a new assignment calls for this craft.

What is ai-thumbnail?

ai-thumbnail is a Claude Code agent skill that shows an agent how to direct or produce "ai thumbnail" so the concrete output is usable copy or a script. The procedure moves through AI-channel thumbnail, Setting a person up, once, When all you have is a video still. Use it when a new assignment calls for this craft.

Works with✓Claude Code~Codex CLI~Cursor✓Gemini CLI
npx skills add https://github.com/lucasaerb/workless-video-editor/tree/HEAD/skills/ai-thumbnail

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

AI-channel thumbnail

Give it a title and a person. It picks a format, samples the look, writes the prompt and generates the image with that person's face in it.

python3 scripts/ai_thumbnail.py --title "Claude vs Gemini for video editing" \
    --person speaker --headline "WHICH ONE WINS" \
    --out drops/drop-021-slug/_FINAL/youtube/thumbnail.jpg --drop drop-021-slug

--prompt-only prints the prompt and calls nothing. Do that first, read it, then run for real. --seed N reproduces an earlier sampling; every generated thumbnail's seed is in brand/people/<person>/history.json.

This skill is for the generated, person-in-frame cover. skills/youtube-thumbnail is the templated card-and-cutout layout and is unaffected; skills/thumbnail still governs IG covers and LinkedIn document covers.

Setting a person up, once

brand/people/<slug>/
    face-front.jpg          head and shoulders, straight down the lens
    face-three-quarter.jpg  turned about 30 degrees
    torso-desk.jpg          seated at a desk, so the model learns build and posture

The references decide the likeness; the prompt barely touches it. Even neutral light, no sunglasses, no hard shadow across the face, 1024px minimum. Bad references cannot be prompted around, and no amount of prompt wording rescues them. The script refuses to run without at least one image in the folder.

When all you have is a video still

Two things help, in this order, and the first matters more:

  1. Add a tight head crop as a second reference. Crop to hair, glasses and chin, upscale it, and drop it in the folder next to the wide one. The model sees a fixed pixel budget per reference, so a crop spends all of it on the face. This is the single biggest lever.
  2. Pass --likeness. It appends a hard identity block: match the face shape, nose, eye spacing, jaw, hairline and curl pattern, keep the stubble as patchy as it really is, and do not "correct" him toward a more conventionally attractive face.

--likeness bends the template rule that a prompt never describes a face. That rule stops the model inventing features it cannot see. When the reference is soft, the model invents anyway, and it always invents in the same direction: straighter nose, sharper jaw, more symmetry, younger. Naming what is already visible in the photo refuses that drift rather than causing it. Leave it off when the references are good; the templates alone do better work.

What the reference channels actually do

Three corrections to the usual assumptions about this genre, all visible in the source thumbnails this was built from:

  • No shock faces. Every subject is calm, composed, looking straight down the lens. This is the "I know how this works, let me show you" register: competence, not reaction. An exaggerated open mouth reads as a lower-trust channel.
  • Real environments, not voids. Wooden desks, a laptop, a curved monitor wall, an actual whiteboard in a bright room. No abstract glowing gradients. The workspace is half the message.
  • Real logos, front and centre. Glossy 3D squircle tiles, held like phones or set inline with the headline. The brand marks are the topic signal; abstracting them away kills the click.

Two more, enforced in every template: hands are always doing something (folded, holding, pointing, capping a marker, never hanging at the sides), and text is a full-width top banner or absent entirely — it never floats in a corner.

The five formats

Routed from the title by keyword; override with --format.

FormatUse forShape
ADesk Anchortool comparison, the fallbackseated, floating logo tiles, top banner
BFace Wraptutorial, full guideextreme close-up, holographic carousel across the eyes
CHands-Up Demoworkflow reveal, "my setup"two objects held up, monitor wall behind, often no text
DWhiteboard Explainerresults, earningsbright room, marker headline, a ladder of numbers
EScreen Pointfeature demooffset, pointing at a laptop showing before → after

B is the most striking; use it sparingly. D is the tonal outlier and breaks up a dark grid.

Templates are formats/A.txt … E.txt, plain text with {{SLOT}} holes. Edit them directly — the script only fills holes, it holds no prompt copy of its own.

The headline is yours to write

The script will not invent one. It is 2-4 words, max 18 characters a line, and it must not repeat the title — it opens a curiosity gap the title then closes. Numbers and dollar figures beat adjectives. Format C can run with no headline at all; let the title carry it.

Every headline is copy, so it goes through /humanizer like all produced writing.

Variance

banks.json holds the expression, hands, hero-object, environment, atmosphere, palette, wardrobe and treatment banks. The script samples one from each, avoiding anything used in the last two thumbnails for that person, and records the whole draw in history.json. Topic- specific holes (what is on the screens, what the before/after shows, the figures on the ladder) come from --slot KEY=VALUE, repeatable:

--slot SCREEN_CONTENT="a different Claude Code terminal session" --slot FIGURE_4="\$40K"

Nothing left unfilled ships: the script exits non-zero and names the slots.

Two-stage, when logos matter

Nano Banana Pro approximates brand marks and kerning and gets both subtly wrong — a mangled Claude sunburst is worse than no logo. So for anything with real product marks:

  1. --blank-tiles generates the plate: person, environment, lighting, glow, and blank white squircle tiles, no text anywhere.
  2. Composite the real PNGs from brand/assets/logos-thirdparty/ onto the tiles and set the headline in actual type. Perfect marks, perfect kerning, and two headlines can be A/B'd against one plate for free.

Single-stage is fine when there are no logos: keep the headline to three words and re-roll the seed on a misspelling rather than rewording. It is usually a seed problem, not a wording one.

9:16 — the Shorts thumbnail

Absorbed from skills/shorts-thumbnail on 2026-08-27, which was deleted in the same pass. Same person folder, same model, same references, same likeness rules and the same tier-3 attribution as everything above; what differs is one layout instead of five, and a two-stage build the 16:9 path does not use.

The vertical sibling of skills/ai-thumbnail. Same person folder, same model, same token, one layout instead of five: face bottom, words top.

Two stages, and the split is the whole point: the model makes the face once, code sets the type every time. Nine thumbnails then share one photograph pixel for pixel, and nine headlines are spelled correctly.

# 1. once per person: the approved 9:16 clean plate. Re-run until it is genuinely him.
python scripts/shorts_thumbnail.py --person speaker --master

# 2. per batch: typeset onto that plate. No model, no API, instant.
python scripts/shorts_thumbnail_type.py brand/people/speaker/face-master.png working/thumbs \
    "Stop wasting tokens|TOKEN BUDGETS" "Do not be the bottleneck|DELEGATING TO AI"

Each positional is HEADLINE|EYEBROW.

Why not just ask the model for the finished thumbnail

Because it re-renders the person every call, and the face lands slightly different every time - a straighter nose here, a sharper jaw there. Nine of those side by side on a channel page read as nine different men. This was the first version of this skill and it failed exactly that way.

Two things caused it, and both are now removed. The prompt described a fresh scene ("he wears X, behind him Y") and randomised wardrobe, environment and light per image for variety; every one of those slots asks for a new photograph and the face gets re-imagined with it. And the prompt was generating rather than editing. master.txt now restores ONE photograph, and prompt.txt (the model-side text path, kept for when there is no plate) edits it rather than recreating it.

The plate is a brand/people/<slug>/face-master.png. --master keeps the previous one as face-master.prev.png, so a bad re-roll costs nothing.

The layout, and why each part is load-bearing

  • Tight head-and-shoulders, eyes just above centre. A Short is read at 200px wide on a phone. A wide shot is a small face, and a small face is nothing.
  • Eyebrow label, small and letterspaced, all caps. It names the topic so the headline does not have to. Two or three words.
  • Serif display headline, white, two or three lines, filling the frame width. Mixed case, not caps - caps at that size read as a banner, mixed case reads as a sentence someone said.
  • One hand-drawn sage stroke under a key word. The only colour in the type. It is the brand accent doing the job an exclamation mark would do badly.
  • Text lives above the eyes. Never across the face. The face is the other half of the click.
  • Bottom fifth and right eighth stay clear - the Shorts title, channel row and the right-hand action rail sit there and will cover anything you put under them.

Background is a real, defocused room. No glowing gradient voids, no neon: those read as a lower-trust channel, same as they do in 16:9.

What the typesetter does

shorts_thumbnail_type.py shifts the plate down 20% and mirrors the wall back up to make room, then sets the eyebrow in Kanit and the headline in brand Fraunces at the largest size that fits - two lines up to five words, three beyond. The sage stroke is drawn under the longest word of the last line, below its real ink rather than its em box, because "prompts" hangs a descender straight through a fixed offset.

It refuses rather than clips: a headline that will not fit at the smallest size exits non-zero and names itself.

Writing the headline

The headline is the hook, so it goes through /humanizer like all produced copy. Six words maximum, plain words, no colon-and-subtitle construction, no emoji. A blunt imperative ("Stop writing longer prompts") beats a claim. Keep the user's own wording when they hand you titles - do not improve them into something they did not say.

Before shipping

  • Downscale to 320x180. Still readable in half a second?
  • Does the face genuinely look like him? Check the nose and hairline — that is where drift shows first, and the box-checkers in this repo cannot see it. Open the file and look.
  • Expression calm, mouth closed or barely open. Hands visible and doing something.
  • Bottom-right 15% clear of anything important (the duration badge sits there).
  • Under 2 MB, JPG.
  • Not the same format + palette as either of the last two uploads — history.json tells you.
  • The prompt, seed and format are logged. After ~30 videos, weight the banks by measured CTR through skills/analytics-flywheel instead of sampling uniformly.

Generated media is tier 3 under config/broll-policy.md: pass --drop so it lands in the drop's _FINAL/ATTRIBUTION.md. Nothing final gets rendered or posted without the human seeing it first.

Before shipping, 9:16 specifically

  • Face check at phone size, once, on the plate. After that the face cannot drift - it is the same file.
  • Read the headline anyway: the typesetter spells what you gave it, including your typo.
  • Bottom fifth and right eighth clear.
  • Under 2 MB, JPG.
  • Nine identical faces IS the intent here - it reads as one series. Re-roll the plate between series, not between thumbnails.

Generated media is tier 3 under config/broll-policy.md: pass --drop so each image lands in that drop's _FINAL/ATTRIBUTION.md. Nothing ships without the human seeing it first.

Individual skills in this repo

This repo contains 2 individual skills — each has its own dedicated page.

Related Skills