thumbnail-creator

缩略图创作技能（通过 Gemini）

在 Claude Code 中充当图像生成 Agent，为文章和新闻简报生成缩略图候选图。无需在不同工具之间切换，也无需每次只向 Gemini 网页界面提交一张图的提示词；此技能让 Claude 完成整个流程：阅读文案、提出构图方案、编写定制提示词、调用 Gemini API、评估生成结果，并返回排序后的结果及简要理由。

输出为可直接用于 CMS、新闻简报工具或社交媒体排期工具的缩略图候选图，可用于正式制作。

---

前置条件

在此技能生成图像之前，必须满足以下两项条件：

1. Gemini API 密钥

从 Google AI Studio 获取免费密钥。

将其设为环境变量：

export GEMINI_API_KEY=<your-key>

若要在不同会话间保留设置，请将其添加到 shell 配置文件（~/.zshrc 或 ~/.bashrc）：

echo 'export GEMINI_API_KEY=<your-key>' >> ~/.zshrc
source ~/.zshrc

确认设置成功：

echo $GEMINI_API_KEY

2. generate_image.py 脚本

此脚本必须存在于项目根目录的 ./generate_image.py。完整模板见下文的“脚本模板”部分。Claude 会检查该文件是否存在；若缺失，则会提出创建。

Python 依赖项：

pip install google-generativeai Pillow requests

或使用 uv：

uv pip install google-generativeai Pillow requests

---

必需输入

如果未提供以下信息，Claude 会向你询问：

输入	必需	说明
文章文案或 URL	是	粘贴完整文章文本，或提供用于抓取的 URL。用于提取主题、吸引点和核心论点，以构思画面。
品牌颜色	建议提供	十六进制代码或颜色描述。例如：#1A1A2E（海军蓝）、#E94560（珊瑚色）。若未提供，Claude 会使用简洁的中性色作为默认设置。
字体／排版风格	建议提供	例如：“粗体无衬线字体”“编辑风格衬线字体”“Neue Haas Grotesk”。用于在提示词中指导文字处理方式。
风格参考描述	建议提供	例如：“扁平插画，极简风格，类似 Stripe 的营销网站”，或“照片级真实感、深色背景、高对比度”。也可以提供风格图片 URL。
输出尺寸	否	默认为 1792x1024（横向，标准文章缩略图）。可选：1024x1024（正方形）、1024x1792（纵向／移动端）。
候选数量	否	默认为 4。最少 1 张，最多 8 张（受 API 限制和费用影响）。
文章标题（如果与 H1 不同）	否	用作图像提示词中的主要文字元素。
候选选择	否	提出构图方案后，Claude 会询问要生成哪些方案。用户可以说“全部”，或按编号选择。

---

输出结构

阶段 1 — 构图提案（文本，在调用任何 API 之前）

Claude 会向用户展示 3-4 个构图概念供其确认。格式如下：

Composition Concepts for: "[Article Title]"

1. BOLD CLAIM
   Layout:    Full-bleed dark background, large white headline centred, 
              single accent data point (e.g. "3x faster") in brand colour below
   Mood:      High authority, newsletter-style
   Best for:  LinkedIn, Substack headers
   Rationale: The article's central claim ("X outperforms Y by 3x") is specific 
              enough to anchor the visual — readers stop on data.

2. CONCEPTUAL OBJECT
   Layout:    Central object illustration (e.g. a broken clock for a time-waste article), 
              title in upper third, minimal texture background
   Mood:      Editorial, Medium-style
   Best for:  Blog header, Medium cover, email preheader
   Rationale: Gives art directors visual metaphor flexibility; works across sizes.

3. CONTRAST SPLIT
   Layout:    Left half brand colour, right half white or image, 
              title on colour side, supporting subtext on white side
   Mood:      Clean, professional, startup-brand feel
   Best for:  Newsletter, LinkedIn carousel first slide
   Rationale: Split layout performs consistently in newsletter A/B tests; 
              text is readable at small sizes.

4. TYPOGRAPHIC ONLY
   Layout:    No illustration, oversized title treatment, 
              author name in small caps at bottom, thin rule separator
   Mood:      Premium, confident, editorial
   Best for:  Substack, Ghost, high-density email lists
   Rationale: Works when the brand has strong type identity. Fastest to produce.

Which compositions do you want generated? (Reply with numbers, e.g. "1, 3" or "all")

阶段 2 — 生成的图像文件

生成完成后，Claude 会将文件保存到 ./thumbnails/[article-slug]/：

thumbnails/
└── article-slug-from-title/
    ├── candidate_01_bold_claim.png
    ├── candidate_02_conceptual_object.png
    ├── candidate_03_contrast_split.png
    ├── candidate_04_typographic.png
    └── evaluation_report.md

阶段 3 — 评估摘要表

Claude 会通过计算机视觉评估每张返回的图像，并生成：

Thumbnail Evaluation — "[Article Title]"
Generated: 2026-05-27  |  Model: Gemini Imagen  |  Dimensions: 1792x1024

| # | Candidate | Composition | Brand Fit /10 | Text Legibility /10 | Recommendation |
|---|---|---|---|---|---|
| 1 | candidate_01_bold_claim.png | Bold Claim | 9 | 8 | ★ Top pick — strong data anchor, brand colours correct, title readable at 200px width |
| 2 | candidate_02_conceptual_object.png | Conceptual Object | 7 | 9 | Good fallback — legible, clean, but illustration style drifted slightly from brand |
| 3 | candidate_03_contrast_split.png | Contrast Split | 8 | 7 | Works well at full size; test at thumbnail size before publishing — right side text tightens |
| 4 | candidate_04_typographic.png | Typographic | 9 | 10 | Strongest for email — zero brand drift risk, completely text-based |

Recommended for web:          candidate_01_bold_claim.png
Recommended for email/mobile: candidate_04_typographic.png
Recommended for social:       candidate_03_contrast_split.png

Files saved to: ./thumbnails/article-slug-from-title/

---

Claude 应如何执行此技能

步骤 1 — 读取并分析文章

接受直接粘贴的文章文案或 URL。

如果提供了 URL，请抓取页面并提取：

• H1 标题
• 前 3-5 段（吸引点、核心论点和要点）
• 提及的重要统计数据或具名框架
• 作者姓名（用于排版构图）

如果粘贴了文本，请直接阅读。重点关注：

• 吸引点： 开篇的主张或矛盾点是什么？
• 核心论点： 文章提出或讲解的最重要观点是什么？
• 关键细节： 是否有能作为视觉锚点的数字、具名框架或具体示例？
• 语气： 正式／权威、轻松／易懂，还是挑衅／挑战性？

在提出构图方案前，先在内部总结这些发现——提案应针对这篇具体文章量身定制，而不是泛泛而谈。

第 2 步 — 收集品牌规范

如果用户未提供品牌规范，请向用户询问：

To generate on-brand thumbnails, I need a few details:

1. Brand colours (hex codes or descriptions) — e.g. #1A1A2E, #E94560
2. Font style preference — e.g. "bold sans-serif", "editorial serif", "geometric"
3. Visual style — e.g. "flat minimal", "photorealistic", "illustrated", "typographic only"
4. Any style references — describe a brand or publication whose aesthetic you want to match, 
   or share an image URL

If you don't have brand specs yet, say "use clean defaults" and I'll use a professional 
dark-on-white editorial style.

如果用户说“使用简洁默认设置”，则应用以下设置：

• 背景：#FFFFFF 或 #0F0F0F（深色模式默认值）
• 强调色：#2563EB（蓝色）
• 字体风格：粗体几何无衬线字体
• 风格：极简扁平，无纹理，高对比度

第 3 步 — 提出构图方案

根据文章的语气和内容，撰写 3-4 个构图方案。每个方案必须：

• 有一个名称（简短、易记的标签）
• 准确描述布局（标题的位置、作为视觉锚点的元素、背景处理方式）
• 说明氛围以及最适用的场景
• 附上一句理由，解释此构图为何适合这篇文章

提出方案后，询问用户想生成哪一个。等待用户确认后再调用任何 API。

第 4 步 — 编写 Gemini 图像生成提示词

针对每个选定的构图，编写详细的图像生成提示词。图像生成提示词遵循与文本提示词不同的语法——它们是描述性的，而非指令式的。

提示词结构：

[Subject/composition] + [Style] + [Colour palette] + [Mood/lighting] + 
[Text treatment if any] + [What to avoid]

“醒目主张”构图的提示词示例：

Article thumbnail image. Large bold white sans-serif headline text reading "3x Faster Than 
Traditional Methods" centred on a deep navy blue background (#1A1A2E). Small coral accent 
text (#E94560) below reading the subtitle. Minimal flat design, no gradients, no stock photo 
elements, no people. Clean professional editorial style, high contrast, newsletter header 
format, 16:9 landscape orientation. The composition is typographic — text is the hero, 
no illustration required. Avoid: clip art, drop shadows, low contrast, crowded layout.

提示词规则：

• 如果用户提供了品牌颜色，请包含准确的十六进制颜色值
• 指定图像中要显示的准确标题文本
• 明确指出风格（“扁平设计”“编辑风格”“照片级写实”等）——Gemini 对风格类别名称响应良好
• 在末尾添加负面提示词（“避免：……”），以减少偏离品牌风格的情况
• 提示词应少于 300 个单词——更长的提示词并不能可靠地带来更好的输出

第 5 步 — 检查前置条件并运行生成脚本

调用 API 前，请确认：

# Check API key is set
echo $GEMINI_API_KEY

# Check script exists
ls -la ./generate_image.py

# Check dependencies
python3 -c "import google.generativeai, PIL, requests; print('Dependencies OK')"

如果缺少脚本，请根据下方“脚本模板”部分的模板，提出为用户创建脚本。

针对每个提示词运行生成脚本：

python3 generate_image.py \
  --prompt "your full prompt here" \
  --output "./thumbnails/article-slug/candidate_01_bold_claim.png" \
  --width 1792 \
  --height 1024

也可以通过批量配置文件传入所有提示词：

python3 generate_image.py --config ./thumbnails/article-slug/prompts.json

第 6 步 — 评估生成的图像

保存每张图像后，使用计算机视觉对其进行检查。根据以下两个维度进行评估：

品牌契合度（评分 /10）：

• 品牌颜色是否正确？（每项 1-2 分）
• 风格是否符合所要求的审美？（2 分）
• 布局是否符合构图要求？（2 分）
• 是否存在 AI 瑕疵、扭曲文本或意外元素？（每项扣 1 分）

文本可读性（评分 /10）：

• 以完整分辨率查看时，标题文本是否清晰可读？（3 分）
• 图像缩放到 300px 宽（缩略图尺寸）时，标题文本是否清晰可读？（3 分）
• 文本与背景之间的对比度是否足够？（2 分）
• 文本是否位于安全区域内（未被边缘裁切）？（2 分）

注意：Gemini Imagen 有时会生成拼写错误或字形扭曲的文本。如果发生这种情况，请在评估中注明，并建议用户在 Canva 或 Figma 中手动添加文本叠层。

第 7 步 — 生成评估报告

编写评估摘要表（格式见“输出结构”部分），并将其保存为输出文件夹中的 evaluation_report.md。

请包含：

• 每项评分的一句话理由
• 针对各使用场景（网页、电子邮件/移动端、社交媒体）的首选推荐
• 任何制作备注（例如：“candidate_02 的文本渲染不够理想——请手动叠加文本”）
• 使用的完整提示词，方便用户在需要时直接前往 AI Studio 继续调整

第 8 步 — 提供迭代机会

交付候选方案后，提供一次迭代机会：

Want me to iterate on any of these?

Options:
- Adjust colours or style on a specific candidate
- Try a different composition concept
- Change the headline text
- Rerun with different Gemini parameters (different temperature/seed)
- Generate additional variants of the top pick

Just tell me what to change.

---

脚本模板

如果不存在 generate_image.py，Claude 应主动提出编写此文件。请使用此规范模板。

#!/usr/bin/env python3
"""
generate_image.py — Gemini Imagen wrapper for Thumbnail Creator skill.

Usage:
    python3 generate_image.py --prompt "..." --output "./out.png" [--width 1792] [--height 1024]
    python3 generate_image.py --config ./prompts.json

Config JSON format:
    [
      {
        "prompt": "...",
        "output": "./thumbnails/slug/candidate_01.png",
        "width": 1792,
        "height": 1024
      }
    ]

Requirements:
    pip install google-generativeai Pillow
"""

import os
import sys
import json
import argparse
import base64
from pathlib import Path

try:
    import google.generativeai as genai
    from google.generativeai import types as genai_types
except ImportError:
    print("ERROR: google-generativeai not installed. Run: pip install google-generativeai")
    sys.exit(1)

try:
    from PIL import Image
    import io
except ImportError:
    print("ERROR: Pillow not installed. Run: pip install Pillow")
    sys.exit(1)


def get_api_key() -> str:
    key = os.environ.get("GEMINI_API_KEY", "")
    if not key:
        print("ERROR: GEMINI_API_KEY environment variable is not set.")
        print("Get a key at: https://aistudio.google.com/app/apikey")
        print("Then run: export GEMINI_API_KEY=<your-key>")
        sys.exit(1)
    return key


def generate_image(
    prompt: str,
    output_path: str,
    width: int = 1792,
    height: int = 1024,
) -> bool:
    """
    Call Gemini Imagen to generate a single image and save it to output_path.
    Returns True on success, False on failure.
    """
    api_key = get_api_key()
    genai.configure(api_key=api_key)

    # Determine aspect ratio from dimensions
    ratio = width / height
    if abs(ratio - 16/9) < 0.1:
        aspect_ratio = "16:9"
    elif abs(ratio - 1.0) < 0.1:
        aspect_ratio = "1:1"
    elif abs(ratio - 9/16) < 0.1:
        aspect_ratio = "9:16"
    else:
        aspect_ratio = "16:9"  # default fallback

    try:
        imagen_model = genai.ImageGenerationModel("imagen-3.0-generate-002")

        result = imagen_model.generate_images(
            prompt=prompt,
            number_of_images=1,
            aspect_ratio=aspect_ratio,
            safety_filter_level="block_only_high",
            person_generation="allow_adult",
        )

        if not result.images:
            print(f"  No images returned for: {output_path}")
            return False

        image_data = result.images[0]

        # Ensure output directory exists
        Path(output_path).parent.mkdir(parents=True, exist_ok=True)

        # Save the image
        if hasattr(image_data, '_image_bytes'):
            img_bytes = image_data._image_bytes
        elif hasattr(image_data, 'image'):
            img_bytes = image_data.image
        else:
            # Fallback: try to access raw data
            img_bytes = bytes(image_data)

        img = Image.open(io.BytesIO(img_bytes))

        # Resize to exact dimensions if needed
        if img.size != (width, height):
            img = img.resize((width, height), Image.LANCZOS)

        img.save(output_path, format="PNG", optimize=True)
        print(f"  Saved: {output_path} ({img.size[0]}x{img.size[1]})")
        return True

    except Exception as e:
        print(f"  ERROR generating image: {e}")
        return False


def run_from_args():
    parser = argparse.ArgumentParser(description="Gemini Imagen wrapper for thumbnail generation")
    parser.add_argument("--prompt", type=str, help="Image generation prompt")
    parser.add_argument("--output", type=str, help="Output file path (.png)")
    parser.add_argument("--width", type=int, default=1792, help="Image width in pixels")
    parser.add_argument("--height", type=int, default=1024, help="Image height in pixels")
    parser.add_argument("--config", type=str, help="JSON config file with batch of prompts")
    args = parser.parse_args()

    if args.config:
        # Batch mode
        with open(args.config, "r") as f:
            items = json.load(f)
        print(f"Batch mode: {len(items)} image(s) to generate")
        results = []
        for i, item in enumerate(items, start=1):
            print(f"\n[{i}/{len(items)}] Generating: {item['output']}")
            ok = generate_image(
                prompt=item["prompt"],
                output_path=item["output"],
                width=item.get("width", 1792),
                height=item.get("height", 1024),
            )
            results.append({"output": item["output"], "ok": ok})

        print(f"\nBatch complete: {sum(r['ok'] for r in results)}/{len(results)} succeeded")
        for r in results:
            status = "OK " if r["ok"] else "ERR"
            print(f"  {status}  {r['output']}")

    elif args.prompt and args.output:
        # Single image mode
        print(f"Generating: {args.output}")
        ok = generate_image(
            prompt=args.prompt,
            output_path=args.output,
            width=args.width,
            height=args.height,
        )
        if ok:
            print("Done.")
        else:
            print("Failed.")
            sys.exit(1)

    else:
        parser.print_help()
        sys.exit(1)


if __name__ == "__main__":
    run_from_args()

在 Claude Code 中创建此文件：

# Claude will write this file if it doesn't exist:
ls ./generate_image.py || echo "Script missing — Claude will create it"

---

提示词编写参考

编写图像生成提示词时，Claude 应使用此参考。这些模式能够让 Gemini Imagen 生成的结果更加一致。

组合模式

组合类型	提示词锚点短语
深色背景、文字主导	“深 [颜色] 背景上的醒目白色无衬线标题文字，极简扁平设计”
浅色背景、文字主导	“干净白色背景上的高对比度黑色标题文字，编辑式布局”
物体／插图居中	“居中的 [物体] 插图，[风格]，[颜色] 背景，标题文字位于上方三分之一区域”
分栏布局	“垂直分栏：左半部分为 [颜色]，右半部分为白色。标题位于左侧，辅助文字位于右侧”
摄影风格	“写实的 [场景描述]，[氛围]光线，[颜色]色调，文字叠加区域位于 [位置]”

与 Gemini 搭配效果良好的风格修饰词

• flat design, no gradients — 输出干净的矢量风格图像
• editorial magazine style — 精致，注重字体排版
• minimal, lots of whitespace — 减少视觉杂乱
• high contrast, bold typography — 缩略图文字清晰醒目
• Bauhaus-inspired — 几何风格，结构分明
• dark mode aesthetic — 深色背景搭配浅色文字
• startup marketing style — 干净、乐观、无衬线

负面提示词（务必包含）

每个提示词末尾都要附加：

Avoid: stock photography clichés, clipart, excessive gradients, drop shadows, 
cluttered layout, lens flares, watermarks, low contrast text, AI artefacts.

文字渲染说明

Gemini Imagen 有时能准确渲染简短的文字短语，但较长的标题效果不佳。如果文章标题超过 6 个词，可以考虑在提示词中拆分标题：

Primary headline: "[First 4-5 words]"
Secondary text:   "[Remaining words]"

或者，如果文字清晰度至关重要，可以指示用户在生成后使用 Canva 手动添加文字叠加层。

---

故障排除

问题	原因	解决方法
GEMINI_API_KEY not set	缺少环境变量	运行 export GEMINI_API_KEY=<your-key> 后重试
ModuleNotFoundError: google.generativeai	缺少依赖项	运行 pip install google-generativeai
No images returned	触发了安全过滤器	修改提示词，移除任何含糊的措辞；检查提示词是否描述了人脸、暴力或品牌徽标
生成的图像包含乱码文字	Imagen 的文字渲染能力有限	在提示词中使用较短的标题，或计划在生成后使用 Canva/Figma 添加文字叠加层
图像尺寸不正确	纵横比不匹配	确认 --width 和 --height 参数符合受支持的比例之一（16:9、1:1、9:16）
generate_image.py not found	尚未创建脚本	请 Claude 使用上方模板创建脚本
API 配额超出	免费套餐限制	等待配额重置，或升级至 Gemini API 付费套餐
风格偏离品牌	提示词不够具体	添加准确的十六进制颜色代码和具体的风格描述词；加强负面提示词

---

质量检查

在标记任务完成前，请逐项确认：

• 在进行任何 API 调用前，确认已设置 GEMINI_API_KEY 环境变量
• 项目根目录中存在 generate_image.py 脚本；若缺失，则根据模板创建
• 已安装并验证所有 Python 依赖项（google-generativeai、Pillow）
• 在进行任何 API 调用前，已展示构图方案并由用户确认要生成哪些方案
• 每个构图方案都针对本文内容，而非通用占位方案
• 图片生成提示词中包含品牌色彩（十六进制代码）
• 每条图片生成提示词后都附加了负面提示词
• 提示词中的标题文字每个文本元素不超过 6 个词（较长的标题应拆分，或注明可后期叠加）
• 已在 ./thumbnails/[article-slug]/ 创建输出文件夹，且根据文章标题生成的 slug 正确
• 文件名包含候选编号和构图名称（candidate_01_bold_claim.png）
• 已通过计算机视觉评估每张生成的图片，而非想当然地认定图片正确
• 品牌契合度和文字易读性评分具体且有依据，不能只是整数
• 在评估中注明任何文字渲染问题，并建议“手动叠加文字”
• 已将评估报告保存为输出文件夹中的 evaluation_report.md
• 针对每种使用场景，至少给出一条建议：网页、电子邮件/移动端、社交媒体
• 评估报告中包含使用过的完整提示词，供用户迭代参考
• 交付结果后提供迭代选项

---

反模式

• 如果用户提供了品牌色彩和风格规范，不要生成未融入这些要求的缩略图——偏离品牌风格的结果必须重新生成
• 不要跳过评估步骤——向用户展示前，必须为所有候选方案评分
• 不要只展示一个缩略图候选方案——始终生成多个选项以供比较
• 不要将完整的图片生成提示词单独放在其他文档中——必须将其纳入评估报告，供迭代参考
• 不要声称缩略图已定稿，却不提供一轮迭代机会

示例触发语

• “为这篇文章创建缩略图”
• “为我的新闻简报生成封面图片候选方案”
• “为这篇帖子给我做 4 个缩略图选项”
• “你能用 Gemini 生成一些缩略图创意吗？”
• “我需要这篇文章的特色图片——请使用我的品牌色彩”
• “用 Gemini 为这篇内容创建缩略图” [后接文章文本或 URL]
• “根据这些品牌规范生成文章封面图片：[色彩、风格]”
• “制作缩略图候选方案并为它们排序”
• “我需要新闻简报标题图片——这是文案”
• “为这份草稿生成并评估缩略图选项”
• “用 Gemini 创建封面图片选项”
• “为这篇文章制作缩略图” [后接文章文本]
• “创建 3 个缩略图构图方案，并选出最佳方案”

---

费用和速率限制

Gemini AI Studio 免费版（截至 2026 年初）：

• Imagen 3：每天 10 张图片（免费）
• 速率限制：因地区和账户级别而异

付费版：

• Imagen 3 价格：每张图片约 $0.03-0.05（请查看当前 Google Cloud 定价）
• 一次典型任务生成 4-8 个候选方案，总费用低于 $0.40

建议：

• 使用免费版进行探索和迭代
• 使用付费版生成最终的生产候选方案，以获得更高的每日限额
• 对于每周都要生成缩略图的新闻简报团队，付费版更实用

---

最初由 Karen Spinner（Wondering About AI）创建——经改编并扩展后纳入本库。