From 78649fa4e19769e9243d70eb9054e531a60787a5 Mon Sep 17 00:00:00 2001 From: seungwonme Date: Fri, 12 Jun 2026 17:44:00 +0900 Subject: [PATCH] feat(codex): document native image generation in /codex skill Codex CLI ships a native image_gen.imagegen tool, but the skill's read-only sandbox rule makes image-generation consults silently fail: the tool call succeeds, the PNG can't be saved. - Add Image Generation section: swap to -s workspace-write for image-making consults, scope writes to a scratch dir under TMP_ROOT (-C + --skip-git-repo-check), show the result to the user - Name this as the sole exception in Important Rules - Regenerate codex/SKILL.md via bun run gen:skill-docs Verified by having Codex enumerate its callable tools and generate a 1254x1254 PNG with code-drawing fallbacks (SVG/matplotlib) forbidden. --- codex/SKILL.md | 25 +++++++++++++++++++++++++ codex/SKILL.md.tmpl | 25 +++++++++++++++++++++++++ 2 files changed, 50 insertions(+) diff --git a/codex/SKILL.md b/codex/SKILL.md index e15c16ec2..2a2ebaf56 100644 --- a/codex/SKILL.md +++ b/codex/SKILL.md @@ -1514,6 +1514,29 @@ or `/codex challenge -m gpt-5.2`), pass the `-m` flag through to codex. --- +## Image Generation + +Codex ships a native image-generation tool (`image_gen.imagegen`) — it produces real +raster images (illustrations, photo-style renders, diagrams) from a text prompt, not +just code that draws SVGs. Verified by having Codex enumerate its tools and generate +a PNG. Image *input* is separate and always available (`codex -i screenshot.png`). + +When a consult asks Codex to MAKE an image (not analyze one): + +1. **Swap the sandbox.** The tool call works in any sandbox, but saving the result + needs write access — run that exec with `-s workspace-write` instead of `-s read-only`. +2. **Scope the writes to a scratch dir.** Point `-C` at a fresh directory under + `$TMP_ROOT` and add `--skip-git-repo-check` (the scratch dir isn't a repo). This + keeps generated files out of the user's repo. +3. **Show the result.** Read the generated image and open it for the user, then + report the file path. + +This is the one exception to "Never modify files" below — image bytes can't come back +inline through the CLI, so writing the file is the deliverable. Writes stay confined +to the scratch directory. + +--- + ## Cost Estimation Parse token count from stderr. Codex prints `tokens used\nN` to stderr. @@ -1541,6 +1564,8 @@ If token count is not available, display: `Tokens: unknown` ## Important Rules - **Never modify files.** This skill is read-only. Codex runs in read-only sandbox mode. + Sole exception: image-generation consults, where Codex writes the generated file to a + scratch directory (see Image Generation). - **Present output verbatim.** Do not truncate, summarize, or editorialize Codex's output before showing it. Show it in full inside the CODEX SAYS block. - **Add synthesis after, not instead of.** Any Claude commentary comes after the full output. diff --git a/codex/SKILL.md.tmpl b/codex/SKILL.md.tmpl index 333de7d8d..14d143725 100644 --- a/codex/SKILL.md.tmpl +++ b/codex/SKILL.md.tmpl @@ -625,6 +625,29 @@ or `/codex challenge -m gpt-5.2`), pass the `-m` flag through to codex. --- +## Image Generation + +Codex ships a native image-generation tool (`image_gen.imagegen`) — it produces real +raster images (illustrations, photo-style renders, diagrams) from a text prompt, not +just code that draws SVGs. Verified by having Codex enumerate its tools and generate +a PNG. Image *input* is separate and always available (`codex -i screenshot.png`). + +When a consult asks Codex to MAKE an image (not analyze one): + +1. **Swap the sandbox.** The tool call works in any sandbox, but saving the result + needs write access — run that exec with `-s workspace-write` instead of `-s read-only`. +2. **Scope the writes to a scratch dir.** Point `-C` at a fresh directory under + `$TMP_ROOT` and add `--skip-git-repo-check` (the scratch dir isn't a repo). This + keeps generated files out of the user's repo. +3. **Show the result.** Read the generated image and open it for the user, then + report the file path. + +This is the one exception to "Never modify files" below — image bytes can't come back +inline through the CLI, so writing the file is the deliverable. Writes stay confined +to the scratch directory. + +--- + ## Cost Estimation Parse token count from stderr. Codex prints `tokens used\nN` to stderr. @@ -652,6 +675,8 @@ If token count is not available, display: `Tokens: unknown` ## Important Rules - **Never modify files.** This skill is read-only. Codex runs in read-only sandbox mode. + Sole exception: image-generation consults, where Codex writes the generated file to a + scratch directory (see Image Generation). - **Present output verbatim.** Do not truncate, summarize, or editorialize Codex's output before showing it. Show it in full inside the CODEX SAYS block. - **Add synthesis after, not instead of.** Any Claude commentary comes after the full output.