A Claude Code skill that generates 4 professional, high-contrast video thumbnail concepts at once — and asks up front whether you want long-form (16:9 horizontal) or short-form (9:16 vertical) before it starts, so the same skill handles YouTube video thumbnails, YouTube Shorts covers, Instagram Reels covers, and TikTok covers.
Uses Gemini 3 Pro Image Preview (Nano Banana Pro) to composite your headshot into each concept, plus optional reference images (logos, screenshots, example thumbnails from top-performing videos in the niche) so the output stays on-brand and on-trend.
Outputs four variations as a.png / b.png / c.png / d.png plus a 2×2 comparison.png grid, so you can react to them side-by-side instead of iterating one at a time.
Credit: this is an improvement on the original
youtube-thumbnailskill that ships with Claude Code, adding first-class short-form (vertical) support, a format-routing front door, UI-safe-zone rules for Shorts/Reels/TikTok, and an explicit setup guide for the free + paid APIs it depends on.
- Long-form + short-form in one skill. Step 0 asks which format you want and routes the rest of the flow accordingly.
- Vertical cover art rules. Proper composition guidance for 9:16 — safe zones for Shorts/Reels/TikTok UI (top header, bottom caption strip, right-side action buttons), larger face sizing, tighter text (1–3 words vs. 3–5).
- Per-format prompt template. Composition, person placement, and text rules swap based on chosen format.
- Per-format quality checklist. Separate safe-zone checks for horizontal vs. vertical.
- Per-format research. Guidance to search for actual shorts/reels as examples when doing vertical work (studying horizontal thumbnails for a vertical project leads you astray).
- Separate output folders. Suggested naming (
{slug}-horizontalvs{slug}-shorts) so batches don't get mixed up.
Everything else — the viewer psychology framework, the 7 stun-gun elements, the desire-loop framing, the 4-concept variation matrix, the iteration loop, the scripts — is intact.
-
Clone this repo (or copy just the
skills/video-thumbnail/folder). -
Drop the skill into your Claude Code skills directory:
cp -R skills/video-thumbnail ~/.claude/skills/ -
Install the Python dependencies the scripts need:
pip install google-genai pillow pillow-avif-plugin
-
Add your headshot photo(s) to
~/.claude/skills/video-thumbnail/assets/headshots/. Tips:- Clear, well-lit face
- Shoulders-up or waist-up framing
- Transparent or simple backgrounds composite best
- Multiple angles/expressions give Claude more to work with
-
Set up environment variables (see below).
-
Restart Claude Code. Then ask Claude something like "make me a thumbnail for my new video about ___" — it'll invoke the skill, ask long-form vs short-form, and take you through the flow.
The skill uses two external APIs. One is free (and the step that uses it is optional — the skill still works without it). The other is paid and required for the actual image generation.
This is what actually generates the thumbnails (via the gemini-3-pro-image-preview model, a.k.a. Nano Banana Pro).
- Where to get it: Google AI Studio — sign in with your Google account and create an API key.
- Cost: pay-as-you-go. Image generation runs through Google's standard Gemini pricing — check the pricing page for current rates. In practice each 4-concept batch costs a few cents.
- Billing: you'll need a Google Cloud billing account attached to use the image-generation model beyond free-tier limits.
- Set it as:
GEMINI_API_KEYin your environment (or in a.envfile at your project root).
Used in Step 1b to search YouTube for high-performing videos on the topic you're making a thumbnail for, then download their thumbnails as style examples for Gemini to study. Skipping this step still works — you just lose the "study what's already winning in the niche" benefit.
- Where to get it: scrapecreators.com — sign up for an account. There's a free tier with enough credits to run this step many times.
- Cost: free tier. Paid plans exist if you hit the free-tier limit.
- Set it as:
SCRAPECREATORS_API_KEYin your environment (or in.env).
Both keys get loaded from a single .env file at the root of whatever project you're working in (or from your shell environment).
Copy .env.example to .env in the root of your working directory and fill in your keys:
cp .env.example .env
# then edit .envGEMINI_API_KEY=your-gemini-key-here
SCRAPECREATORS_API_KEY=your-scrape-creators-key-here
.env is gitignored — don't commit it.
Once installed, just ask Claude in natural language. Example prompts:
- "make me a thumbnail for my new video on Claude Code agents"
- "I need cover art for a Short about AI coding tools"
- "can you design 4 thumbnail variations for 'How I Made $10k With Claude'"
The skill will:
- Ask long-form or short-form (Step 0)
- Ask if any specific logos / products / tools should appear
- Optionally search YouTube for top-performing examples in the niche (if Scrape Creators is configured)
- Design 4 genuinely different concepts (not just color swaps)
- Fetch any reference images it needs (logos, screenshots, etc.)
- Generate all 4 concepts in parallel against Gemini
- Combine them into a single 2×2 comparison grid
- Present them to you and iterate based on your feedback
Output lands in workspace/{today}/thumbnails/{video-slug}-{format}/.
skills/video-thumbnail/
├── SKILL.md # the skill itself (what Claude reads)
├── assets/
│ └── headshots/
│ └── README.md # drop your headshot photos here
└── scripts/
├── generate_thumbnail.py # calls Gemini with prompt + images
├── search_examples.py # pulls high-performing examples via Scrape Creators
└── combine_thumbnails.py # builds the 2×2 comparison grid
You can also add an optional skills/video-thumbnail/brand-style.md file — if present, its contents get auto-appended to every generation prompt, so you can lock in your own brand colors, typography, and visual identity.
Built on top of the youtube-thumbnail skill pattern that ships with Claude Code. This version extends it into a proper long-form + short-form generator with format-aware composition rules.
MIT — see LICENSE.