CommunityImagegithub.com

codex-image-director

Native Codex CLI image generation director: composition design, prompt control, and acceptance verification. Used when users want to generate images, generate based on reference images, refine or repair existing images, change outfits or camera angles for redesign, create character series or variant comparisons, or mention Codex image generation.

What is codex-image-director?

This skill enables an AI agent to act as an image director within the Codex CLI environment, managing the end-to-end process of generating, editing, and iterating on images. It is particularly useful for developers who need to create visual assets, character series, or variant explorations using AI generation tools, ensuring consistent quality and controlled iterations. The skill supports platforms like Codex CLI and follows a structured workflow that includes composition design, prompt engineering, script-based generation, acceptance review, and single-variable refinement. It enforces a closed-loop process (design → specification → execution → self-verification → single-variable fix) to achieve precision without relying on magical keywords, and includes decision modes (ask, auto, mixed) to manage trade-offs during execution.

Works with~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/SherlockGy/codex-image-director/tree/main

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

Codex Image Director

Behavioral Overrides

  • First, read the task scale and workflow table below to select a single workflow, then read that specific workflow document before proceeding.

    • Do not write prompts, call Codex, or read deep files in catalog/ before this.
  • After selection, reply with:

    Using <workflow>[·<tier>], based on: user mentioned <original phrase>; decision mode: <ask/auto/mixed>; next read <file>
    
  • If two or more rows in the table match, or none match, stop and ask the user instead of assuming a workflow.

  • Image generation credit consumption is significantly higher than normal conversation rounds (research note from 2026-11: approximately 3–5x). Do not batch generate images "just to try." Only change one variable per iteration.

Image Generation Pipeline

User request
  │
  ▼
Composition design – fill unspecified dimensions / infer physics and geometry / anticipate conflicts / optimize for easy generation      ← agent: director
  │
  ▼
Prompt file (English, segmented tags)  [+ fixed specification file]  [+ reference images / base images]
  │
  ▼
scripts/gen.py ──▶ codex exec (read-only sandbox) ──▶ built-in image_gen        ← Codex: executor; image_gen: artist
  │                    Wrapper prompt must call once as-is, no rewriting, no self-checking
  ▼
$CODEX_HOME/generated_images/<thread_id>/ ──▶ output directory name-vNNN.<ext> (never overwrite previous versions)
  │
  ▼
Agent reviews each image themselves, checking details at full zoom                              ← agent: QA
  │
  ▼
Single-variable fix: edit / regenerate / local patch (scripts/patch_region.py)

Precision comes from the closed outer loop (design → specification → execution → self-verification → single-variable fix), not from any keyword. See README.md for the rationale (for human reading; not needed during execution).

Terminology

TermMeaning
Base imageThe image being edited in edit mode; written as Image N is the edit target in the prompt
Reference imageAn image from which only specified elements are borrowed, without being modified; specify what is borrowed and what is not for each
Lock listElements that must remain unchanged in the current iteration, listed individually—not just "everything else stays the same"
Fixed specification fileCharacter, art style, and physics rules shared across multiple images; appended using --spec before each image's spec
Edit / RegenerateEdit: keep the base image composition, modify only a region; Regenerate: redraw entirely from the prompt, optionally with reference images
Local patchUse the old image as a base, paste only the target region pixels from the new image; used as a fallback to fix drift during editing
Realism scaleA continuous range from flat illustration to photorealistic, with anchor terms for each tier
Decision pointA place in the workflow where a trade-off is needed; each workflow has a Decision Point table specifying options, auto defaults, and cases requiring mandatory consultation

Task Scale and Workflows

Read the full table first, then select a workflow.

WorkflowIntent signal (typical phrasing)First stepDesign depthExpected iterationsFile
Single image·fast tierWant a new image, quick sketch, draft, "just draw something"Directly design and generateOnly complement shot, style, lighting1–2 roundsflows/single-image.md
Single image·premium tierWant a new image, long description, emphasizes drama or texture, gave reference imagesFill all dimensions, infer physics geometryFull dimensionsMultiple rounds, usually regenerate first to set the big picture, then refineflows/single-image.md
Series / character projectMultiple images of the same character or universe, needs consistency, wants spec sheets or three-view drawingsFirst-principle questions + create project directorySet specs first, then scenesMultiple rounds in spec phase, 1–2 rounds per scene, then polishflows/series-project.md
Variant explorationForm not yet decided, "give me several options", wants to compare and chooseDefine invariants and exploration axesEach direction varies only one axisDiverge → select → convergeflows/explore-variants.md
Refine existing imageOnly change a region, "fix the hand", "everything else stays the same", "remove something"Describe current mistake + lock listOnly describe the changeOne change per roundflows/edit-refine.md
Redesign existing imageChange outfit, form, art style, camera angle, recomposition, while keeping face or some elementsList preserved and replaced elementsLock preserved items, fully design replaced items2–4 roundsflows/redesign.md
MaintenanceMaintain this skill: add experience, adjust workflows or scripts, recalibrate trigger descriptionsDetermine which layer to place it——flows/maintain.md

Common misrouting:

  • "Edit this image":
    • If only a region changes, use Refine.
    • If composition, shot, outfit, subject, or art style changes, use Redesign. When unsure, ask the user.
  • "Move the person to lower left" or "Rotate the shot": These are composition-level changes; edit mode usually can't handle them—use Redesign or Single Image Regenerate, not Refine.
  • "Generate more images":
    • Same character, different scenes → use Series.
    • Same request, different design directions → use Variant Exploration.

Decision Modes

Where trade-offs are needed during execution, they are listed in each workflow's Decision Point table. Handle them based on the user's authorization level:

ModeTriggerBehavior
Ask (default)User hasn't expressed a preferencePresent decision points as multiple-choice questions, with the recommended option first and a rationale; ask all questions for the same phase at once, no fragmented follow-ups
AutoUser says "you decide", "use your judgment", "make the call", "otherwise go with your approach"Execute according to the "auto default" in the Decision Points table; deliver with a list of "Decisions I made for you": decision, rationale, how to override
MixedUser authorizes only part—e.g., "you choose the shot, but ask me about the clothes"Execute authorized parts as Auto, the rest as Ask

Even in Auto mode, you must stop and ask (hard gate) in these cases:

  • Overriding a setting or request the user has confirmed.
  • Significantly increased credit consumption: generating more than 3 images at once, or more than 2 auto-refinement rounds on the same issue.
  • Missing prerequisites: reference images from disallowed sources, Codex unavailable.
  • User's request is contradictory and cannot be satisfied simultaneously.
  • Items marked as "always ask" in any workflow's Decision Point table.

Auto-mode refinement:

  • Structural defects (extra fingers, broken lines, counting errors, violating requirements) may be auto-refined, maximum 2 rounds per issue.
  • Aesthetic trade-offs (finer vs. stronger, cooler vs. warmer) are not auto-refined; they are listed in the delivery as "Optional directions" for the user to choose.

Boundaries

  • Reference images must be provided by the user or explicitly allowed. If the user requests "don't use intermediate results," previously generated images must not be used as references or base images.
  • Outputs are saved with new version numbers, never overwriting existing files.
  • The generating party (Codex or other agent) self-declarations about results are not considered verification; you must inspect the image yourself.
  • When Codex is unavailable, not logged in, or has insufficient credits, stop and report; do not bypass or use an unauthorized generation channel.
  • When canceling a generation mid-way, confirm that the Codex subprocess has ended, otherwise it will continue consuming credits.
  • When drawing inspiration from others' work, borrow only the design language, not the exact shape; do not write work names, game names, or brand names in prompts—describe the rendering technique instead.

Related Skills