Back to Details

generate-image

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

generate-image: images for coding agents, handed back into the chat

generate-image：为 coding agents 生成图片，并返回到聊天中

Generate production-ready imagery while you build, then show it to the user. Images are saved straight into the project as exact-size 
.webp
/
.png
/
.jpg
.
在构建过程中生成可用于生产环境的图像，然后向用户展示。 图像会以精确尺寸直接保存到项目中，格式为 
.webp
/
.png
/
.jpg
。

Backends: who actually makes the pixels

后端：究竟由谁生成像素

BackendWhat it isCostNeeds
codex
(default when available)		Codex CLI's built-in 
image_gen
tool (OpenAI's GPT Image)		the user's ChatGPT plan
codex
installed and 
codex login
with ChatGPT
local
FLUX.1-schnell via mfluxfree, offlineApple Silicon Mac, ~7 GB one-time model download
openai
/ 
gemini
/ 
replicate
hosted APIsper image, on the user's API accounta key stored with 
--set-key
--backend auto
(the default) picks 
codex
if Codex is signed in with ChatGPT, otherwise 
local
. You (Claude) cannot call Codex's image tool directly; this skill runs 
codex exec
headless for you, then collects the finished file from 
~/.codex/generated_images/
and crops it to the exact size you asked for.
后端是什么费用所需条件
codex
（可用时默认）		Codex CLI 内置的 
image_gen
工具（OpenAI 的 GPT Image）		用户的 ChatGPT 套餐已安装 
codex
，并已通过 ChatGPT 执行 
codex login
local
通过 mflux 使用 FLUX.1-schnell免费、离线Apple Silicon Mac、一次性下载约 7 GB 模型
openai
/ 
gemini
/ 
replicate
托管 API按张计费，使用用户的 API 账户使用 
--set-key
存储的 key
--backend auto
（默认）会在 Codex 已登录 ChatGPT 时选择 
codex
， 否则选择 
local
。你（Claude）无法直接调用 Codex 的图像工具；该 Skill 会以无界面模式为你运行 
codex exec
，然后从 
~/.codex/generated_images/
收集完成的文件，并 裁剪到你要求的精确尺寸。

When to use and when NOT to

何时使用，何时不要使用

Generate: hero images, section backgrounds, textures, spot illustrations, og:images (1200x630), product/editorial photography, empty-state art, transparent cut-outs, and edits or variations of an existing image.
Don't generate: logos, icons, and UI screenshots. Use SVG for logos and icons, and real screenshots for UI. On 
codex
a short headline in the image renders well. On 
local
(FLUX), keep legible text to 1–2 words at most. In both cases, put real page copy in HTML/CSS over the image.
生成： 主视觉图、区块背景、纹理、局部插画、 og:images（1200x630）、产品/编辑类摄影、空状态插图、 透明背景抠图，以及对现有图像的编辑或变体。
不要生成： logo、图标和 UI 截图。Logo 和 图标应使用 SVG，UI 应使用真实截图。在 
codex
后端中，图像里的短标题 渲染效果很好。在 
local
（FLUX）后端中，清晰可辨的文字最多只保留 1–2 个词。 两种情况下，都应将真实的页面文案通过 HTML/CSS 叠加在图像上。

Setup: do this first (once per session)

设置：每个会话先执行一次

bash
python3 <SKILL_DIR>/scripts/doctor.py
It needs only the system 
python3
. Act on what it reports; don't make the user troubleshoot:
  • ! Codex CLI not installed
    / 
    not signed in with ChatGPT
    : if the user has a ChatGPT plan, this is the best backend. Offer 
    npm install -g @openai/codex
    . The sign-in (
    codex login
    ) opens a browser, so the user runs it themselves.
  • ✗ uv is not installed
    : offer 
    brew install uv
    (or 
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ), then re-run the doctor.
  • Local-only items (
    platform
    , 
    disk
    , 
    model not downloaded
    ) only matter for 
    --backend local
    . When Codex is ready they are advisory.
When it says "Ready to generate", go ahead. The doctor also prints the backend 
auto
will use.
bash
python3 <SKILL_DIR>/scripts/doctor.py
它只需要系统 
python3
。根据它的报告采取相应措施；不要让用户自行排查 问题：
  • ! Codex CLI not installed
    / 
    not signed in with ChatGPT
    ：如果用户 有 ChatGPT 套餐，这是最佳后端。建议执行 
    npm install -g @openai/codex
    。登录（
    codex login
    ）会打开浏览器，因此必须由用户 自行运行。
  • ✗ uv is not installed
    ：建议执行 
    brew install uv
    （或 
    curl -LsSf https://astral.sh/uv/install.sh | sh
    ），然后重新运行 doctor。
  • 仅限本地的事项（
    platform
    、
    disk
    、
    model not downloaded
    ）仅在 
    --backend local
    时才需要关注。Codex 就绪后，这些信息仅供参考。
当它显示“Ready to generate”后，即可继续。doctor 还会打印 
auto
将要使用的 后端。

How to run: in the background

如何运行：在后台执行

The script lives in THIS skill's directory, not the user's project:
bash
uv run <SKILL_DIR>/scripts/generate.py "PROMPT" --out public/hero.webp --size 1440x800 --json
Run it as a background task. If you have a background option (Claude Code: Bash with 
run_in_background: true
), use it. You'll be notified when it exits, so keep working meanwhile and don't poll. Timing: 
codex
takes ~30–60 s per image; 
local
takes ~40–90 s, plus several minutes for the ~7 GB model on first use. If you must run it in the foreground, set the timeout to at least 10 minutes.
--json
prints one line per saved image, e.g. 
{"path": "/abs/public/hero.webp", "width": 1440, "height": 800, "seed": 1, "backend": "codex"}
. Use those absolute paths in the next steps.
脚本位于此 Skill 的目录中，而不是用户的项目中：
bash
uv run <SKILL_DIR>/scripts/generate.py "PROMPT" --out public/hero.webp --size 1440x800 --json
将其作为后台任务运行。 如果你有后台运行选项（Claude Code：使用 
run_in_background: true
的 Bash），请使用它。任务退出时会收到 通知，因此可以继续处理其他工作，不要轮询。耗时：
codex
每张图约 30–60 秒；
local
每张约 40–90 秒，首次使用还需几分钟下载约 7 GB 的模型。 如果必须在前台运行，请将超时设置为至少 10 分钟。
--json
会为每张已保存的图像输出一行，例如： 
{"path": "/abs/public/hero.webp", "width": 1440, "height": 800, "seed": 1, "backend": "codex"}
。 在后续步骤中使用这些绝对路径。

Hand the image back: always do both

将图像交回：始终执行两项操作

  1. Look at it yourself. Read the image file before wiring it into the page. If it's wrong, regenerate with a more concrete prompt; don't ship unseen images.
  2. Show it to the user in the chat. Don't leave a path buried in tool output. Use the best option the environment has:
    • A tool that sends or renders files to the user (in the Claude desktop app: 
      SendUserFile
      with 
      display: "render"
      ). This shows the image inline, the way Codex does. Prefer this whenever it exists.
    • Otherwise put a markdown image in your reply, 
      ![hero](/abs/path/hero.webp)
      , and the plain absolute path. Orcha and most IDE chats turn the path into a clickable link.
    • Terminal-only: 
      --open
      opens results in Preview, and 
      imgcat <path>
      (iTerm2) or 
      kitten icat <path>
      (Kitty/Ghostty/WezTerm) render inline.
  1. 亲自查看图像。 在将图像接入页面前，先读取该图像文件。 如果图像有误，请使用更具体的提示词重新生成；不要交付未经查看的 图像。
  2. 在聊天中向用户展示。 不要把路径埋在工具输出中。请使用环境中 最佳的方式：
    • 可向用户发送或渲染文件的工具（在 Claude 桌面应用中：使用 
      SendUserFile
      并设置 
      display: "render"
      ）。这会像 Codex 一样 内联展示图像。只要存在此工具，就优先使用。
    • 否则，在回复中放入 Markdown 图像， 
      ![hero](/abs/path/hero.webp)
      ，并附上纯文本绝对路径。Orcha 和 大多数 IDE 聊天会将该路径转换为可点击链接。
    • 仅限终端：
      --open
      会在 Mac 默认查看器中打开结果，而 
      imgcat <path>
      （iTerm2）或 
      kitten icat <path>
      （Kitty/Ghostty/WezTerm）会内联渲染。

Flags

参数

FlagMeaning
--out PATH
Output file; format from extension: 
.webp
(best for web), 
.png
, 
.jpg
--size WxH
Exact output pixels, e.g. 
1440x800
. The image is cover-cropped to it
--backend
auto
(default), 
codex
, 
local
, 
openai
, 
gemini
, 
replicate
--transparent
Real transparent background (
codex
only; 
.png
or 
.webp
output)
--ref IMAGE
Reference or edit-source image, repeatable (
codex
only). Say in the prompt how to use it ("edit this photo: replace only the sky")
--count N
N candidates as 
name-1.webp
, 
name-2.webp
, …
--batch FILE
JSON array of 
{prompt, out, size, seed?, count?}
. 
codex
runs 3 jobs at once; 
local
loads the model once
--json
Machine-readable result line per image
--seed N
Reproducible output on 
local
/
replicate
; 
codex
ignores seeds
--steps N
, 
--model REPO
Local FLUX tuning (advanced)
--no-style
Ignore the project's 
imagegen.toml
--open
Open each result in the Mac's default viewer
--dry-run
Print the plan (styled prompts, sizes) without generating
参数含义
--out PATH
输出文件；格式由扩展名决定：
.webp
（最适合 Web）、
.png
、
.jpg
--size WxH
精确的输出像素尺寸，例如 
1440x800
。图像会按 cover 方式裁剪为该尺寸
--backend
auto
（默认）、
codex
、
local
、
openai
、
gemini
、
replicate
--transparent
真正的透明背景（仅 
codex
；输出为 
.png
或 
.webp
）
--ref IMAGE
参考图或编辑源图，可重复指定（仅 
codex
）。在提示词中说明如何使用它（“仅编辑这张照片：替换天空”）
--count N
N 个候选图，命名为 
name-1.webp
、
name-2.webp
等
--batch FILE
包含 
{prompt, out, size, seed?, count?}
的 JSON 数组。
codex
会同时运行 3 个任务；
local
只加载一次模型
--json
为每张图像输出一行机器可读的结果
--seed N
在 
local
/
replicate
上生成可复现的输出；
codex
会忽略 seed
--steps N
、
--model REPO
调整本地 FLUX（高级用法）
--no-style
忽略项目的 
imagegen.toml
--open
在 Mac 默认查看器中打开每个结果
--dry-run
仅打印生成计划（带样式的提示词、尺寸），不生成图像

Workflow rules

工作流规则

  1. Plan all assets first, then generate them in one 
    --batch
    , in the background.
  2. Generate 1–2 candidates, not 10. Each 
    codex
    image uses the user's plan quota; each 
    local
    image costs about a minute.
  3. Always view, then show (see "Hand the image back").
  4. Record what you shipped in the commit message: the prompt, the backend, and the seed when the backend supports one.
  5. Set up style once: if the project has no 
    imagegen.toml
    , consider creating one (copy 
    imagegen.example.toml
    from this skill's directory) so all assets share an art direction.
  1. 先规划所有素材，再通过一次 
    --batch
    统一生成    ， 并在后台执行。
  2. 只生成 1–2 个候选方案，不要生成 10 个。 每张 
    codex
    图像都会 消耗用户套餐的配额；每张 
    local
    图像约需一分钟。
  3. 务必先查看，再展示（参见“将图像交回”）。
  4. 在提交信息中记录交付内容：提示词、后端，以及后端支持时所用的 seed。
  5. **只设置一次风格：**如果项目没有 
    imagegen.toml
    ，可考虑创建一个 （从此 Skill 的目录复制 
    imagegen.example.toml
    ），让所有素材共享统一的 艺术方向。

Writing good prompts

如何编写优质提示词

Both backends reward specific, concrete descriptions and punish one-word prompts. Every prompt should cover:
  • Subject: the concrete thing ("handmade ceramic bowls", not "something nice")
  • Setting: where it is and what surrounds it
  • Lighting: direction and quality ("soft morning light from the left")
  • Mood and palette: the feeling and the colors
  • Composition: framing and negative space, especially where text will overlay ("subject on the right third, empty space on the left for a headline")
On 
codex
, a short labeled spec works especially well. This is the format Codex's own image skill uses:
text
Use case: product-mockup
Asset type: landing page hero
Primary request: a ceramic coffee mug on a linen tablecloth
Style/medium: clean product photography
Composition/framing: wide, mug on the right third, empty space on the left for copy
Lighting/mood: soft window light, calm morning
Constraints: no logos, no watermark
For edits with 
--ref
, list what must stay the same ("change only the background; keep the product and its edges unchanged").
Weak → strong:
❌ 
a coffee shop
✅ 
warm natural-light photograph of a cozy independent coffee shop interior at golden hour, exposed brick walls, a barista blurred in the background, steam rising from a cup in the foreground, shallow depth of field, inviting mood
两种后端都偏好具体、明确的描述，并会“惩罚”过于简短的单词式提示词。每个提示词都应涵盖：
  • 主体：具体事物（“手工陶瓷碗”，而不是“好看的东西”）
  • 环境：事物所在的位置及周围环境
  • 光线：方向和质感（“从左侧照来的柔和晨光”）
  • 氛围和配色：感觉与颜色
  • 构图：取景和留白，尤其是文字将要叠加的位置（“主体位于右侧三分 之一，左侧留出用于标题的空白”）
在 
codex
后端中，采用简短且带标签的规格尤其有效。Codex 自带的图像 Skill 使用以下格式：
text
Use case: product-mockup
Asset type: landing page hero
Primary request: a ceramic coffee mug on a linen tablecloth
Style/medium: clean product photography
Composition/framing: wide, mug on the right third, empty space on the left for copy
Lighting/mood: soft window light, calm morning
Constraints: no logos, no watermark
使用 
--ref
进行编辑时，请列出必须保持不变的内容（“仅更改背景；保持产品及其边缘不变”）。
弱 → 强：
❌ 
一间咖啡馆
✅ 
黄金时段下独立咖啡馆内部温暖自然的实景照片，裸露的砖墙，背景中虚化的咖啡师，前景杯中升起热气，浅景深，氛围温馨

Choosing dimensions: always set 
--size
deliberately

选择尺寸：始终明确设置 
--size

AssetSize
Full-width hero
1440x800
(or 
2880x1600
for retina)
Wide banner strip
1200x360
Section background
1440x600
og:image / social card
1200x630
Square spot illustration
800x800
Portrait / mobile hero
800x1200
素材尺寸
全宽主视觉图
1440x800
（Retina 屏使用 
2880x1600
）
宽幅横幅条
1200x360
区块背景
1440x600
og:image / 社交卡片
1200x630
方形局部插画
800x800
竖版/移动端主视觉图
800x1200

Hosted API keys (optional)

托管 API key（可选）

Only needed for 
openai
, 
gemini
, or 
replicate
. The user stores a key once at a hidden prompt; never ask them to paste a key into the chat:
bash
uv run <SKILL_DIR>/scripts/generate.py --set-key openai   # or: gemini, replicate
The key goes into the macOS Keychain, and the CLI reads it at run time. This command refuses to run non-interactively, so you can't run it for them. 
--list-keys
shows which providers have a key; 
--delete-key <provider>
removes one.
仅在使用 
openai
、
gemini
或 
replicate
时需要。用户只需在隐藏输入提示中 存储一次 key；绝不要要求用户将 key 粘贴到聊天中：
bash
uv run <SKILL_DIR>/scripts/generate.py --set-key openai   # or: gemini, replicate
key 将保存到 macOS Keychain，CLI 会在运行时读取。该 命令拒绝以非交互方式运行，因此你无法代替用户执行。 
--list-keys
显示哪些提供商已配置 key；
--delete-key <provider>
用于删除 key。

Reference

参考

See 
reference/prompting.md
in this skill's directory for per-asset-type prompt recipes (hero, texture, illustration, og:image, photography).
有关各类素材的提示词配方（主视觉图、纹理、插画、og:image、摄影），请参阅此 Skill 目录中的 
reference/prompting.md
。