---
name: youtube-thumbnail
description: "Skill for creating and editing Youtube thumbnails that are optimized for click-through rate. Use when the user asks to create a thumbnail from scratch or edit an existing thumbnail."
---

# YouTube Thumbnail Skill

This skill enables generation of high-performing YouTube thumbnails optimized for click-through rate (CTR). Thumbnails are designed to spark curiosity, complement titles, and compel viewers to click.

## Thumbkit

This skill uses Thumbkit, a CLI tool for generating and editing high-performing YouTube thumbnails. Thumbkit is built on top of Gemini 2.5 Flash (NanoBanana) image generation model. 

Thumbkit is **required** for this skill. Assume Thumbkit has been installed as a uv tool and is available globally on the user's system. If Thumbkit is not installed, please install it before proceeding.

### Testing Installation

To test if Thumbkit is installed, run the following command:

```bash
thumbkit
```

If you see the help menu, Thumbkit is installed.

### Installation

```bash
uv tool install https://github.com/kenneth-liao/thumbkit.git
```

### Upgrading

```bash
uv tool upgrade thumbkit
```

### Thumbkit Documentation

To access the full CLI reference documentation, run the following command:

```bash
thumbkit docs
```

If not accessible through the CLI, the full documentation for Thumbkit can be found at `https://github.com/kenneth-liao/thumbkit/blob/main/thumbkit/CLI_REFERENCE.md`.

**CRITICAL**: You **MUST** read the full documentation before using Thumbkit to generate thumbnails.

### Thumbnail Output Directory

By default, thumbnails generated by Thumbkit are saved to `./youtube/thumbnails/` in the user's current working directory. You should always save newly generated thumbnails to this directory unless otherwise specified by the user. To specify a different directory, use the `--output-dir` flag and pass the absolute path to the desired directory.

## 🚨 REQUIRED READING 🚨

The following documents are **MANDATORY READING**. You **MUST** read both documents before generating ANY thumbnail.

1. You **MUST** read the complete Thumbkit CLI reference documentation by running `thumbkit docs`.
2. `references/design-requirements.md` - The design requirements are what enable you to generate high click-through-rate thumbnails through proven strategies.
3. `references/prompting-guidelines.md` - Thumbnails are generated using NanoBanana, an image generation large language model. The prompting guidelines will enable you to get more predictable and consistent results from NanoBanana.

It's a **MANDATORY REQUIREMENT** that you follow both the design requirements and prompting guidelines in order to generate high converting thumbnails. Failure to do so will result in a failed task.

## Reference Images

With both generating and editing thumbnails, you can include reference images. Examples include but are not limited to base thumbnails to edit, thumbnail templates, the user's headshots, icons, logos, or images for style transfer.

All reference images **MUST** be passed using absolute paths.

### Using Official Logos

If using company logos, use actual images by passing the absolute path to the image files instead of simply describing them. Nanobanana does not know what common company logos look like.

If a company logo is not locally available, you can search for it online and download it using curl, then pass the absolute path to the downloaded image in the prompt. Save all downloaded images to `./youtube/downloads/`, making the dir if it doesn't exist.

### Common Mistakes to Avoid

❌ **WRONG**: "create the Claude AI logo (an orange C shape)"
✓ **CORRECT**: Pass the actual logo file as a reference image

❌ **WRONG**: "add the Python logo"
✓ **CORRECT**: Use `/absolute/path/to/python-logo.png` as a reference image

## Workflows

### Generating Thumbnail Concepts

Once you have generated an initial thumbnail concept or prompt, you **MUST** use the `Thumbnail Reviewer` agent to review the concept and provide feedback. The reviewer will provide a critique and suggest improvements. Refine the prompt before proceeding to generate the thumbnail.

### Generating Thumbnails from Scratch

For most cases, you will be editing a base image to preserve all of or most of the original image, such as with a template or a headshot. However, when the goal is to generate a new thumbnail where preserving original reference images is not important, you can generate a new thumbnail from scratch.

### Editing Base Images

For most cases, you will be editing a base image to preserve all of or most of the original image, such as with a template, headshot, or example thumbnails. If a user has provided a headshot but no base image to edit, use the headshot as the base image. This ensures the original headshot is used without modification. When using headshots as reference images rather than base images, they are loosely replicated, not exactly copied. This can result in the person in the final image looking different from the original headshot.

### Face Swapping / Person Replacement Best Practices

Face swapping with AI image generation is unreliable. The model tends to generate new faces rather than accurately preserving reference faces.

#### Recommended Approach

1. Use Headshot as Base Image (BEST)
When to use: When you need the person's face to be accurate Instead of generating a thumbnail and trying to swap faces, use the headshot as the base image and build the thumbnail around it.
thumbkit edit \
  --prompt "Create a YouTube thumbnail using the person from this headshot. Place them on the [left/right] side with [pose/gesture]. Add [background elements, text, graphics]. The person should maintain their exact facial features from the headshot." \
  --base "/path/to/headshot.png" \
  --ref "/path/to/style-reference.jpg" \
  --out-dir "/path/to/output"
Why it works: The model preserves the base image's face more accurately than when trying to swap faces onto a different person.

#### What Doesn't Work

Using headshot as reference only: When the headshot is just a reference (not base), the model loosely interprets facial features rather than copying them exactly
Simple face swap prompts: Prompts like "replace the face with Kenny's face" produce inconsistent results
Multiple generation attempts: Regenerating rarely improves face accuracy

#### Example: Building Thumbnail Around Headshot

Good - headshot as base
```bash
thumbkit edit \
--prompt "Create a YouTube thumbnail using the person from this headshot. Place them on the left side with a thumbs up gesture. Add a blueprint-style diagram on the right showing a workflow. Add text 'this plans my videos' at the top. The person should maintain their exact facial features." \
--base "/Users/name/headshots/excited-face.png" \
--ref "/Users/name/examples/style-reference.jpg" \
--out-dir "./thumbnails"
```

### Optimizing Thumbnails

Because you can edit a base image with Thumbkit, you can iteratively modify/improve a previously generated thumbnail. For example, if you've generated a thumbnail but want to change the color scheme, you can pass the generated thumbnail's absolute path as a reference image and ask NanoBanana to make the necessary updates.

Always review generated thumbnails to ensure they meet the complete design requirements and original intent. If not, suggest improvements to the user and ask if they want you to iterate. 

## User Assets

If the user has specified any local assets (e.g. thumbnail templates, headshots, icons, logos, etc.) in their local context, bias towards incorporating them into the thumbnail when relevant.
