imagegen

画像生成スキル

現在のプロジェクト向けに、画像を生成または編集します（例：ウェブサイト素材、ゲーム素材、UI モックアップ、製品モックアップ、ワイヤーフレーム、ロゴデザイン、フォトリアル画像、インフォグラフィック）。

最上位のモードとルール

このスキルには、最上位のモードが厳密に 2 つあります。

• デフォルトの組み込みツールモード（推奨）： 通常の画像生成と編集には、組み込みの image_gen ツールを使用します。OPENAI_API_KEY は不要です。
• フォールバック CLI モード（明示的な指定がある場合のみ）： scripts/image_gen.py CLI を使用します。ユーザーが CLI の利用を明示的に求めた場合にのみ使用します。OPENAI_API_KEY が必要です。

明示的に指定された CLI フォールバック内では、CLI で次の 3 つのサブコマンドを使用できます。

• generate
• edit
• generate-batch

ルール：

• 通常の画像生成と編集のリクエストには、デフォルトで組み込みの image_gen ツールを使用してください。
• CLI フォールバックへ自動的に切り替えないでください。
• 組み込みツールが失敗した場合や利用できない場合は、CLI フォールバックが利用可能であり、OPENAI_API_KEY が必要なことをユーザーに伝えてください。ユーザーがそのフォールバックを明示的に求めた場合にのみ続行してください。
• ユーザーが CLI モードを明示的に求めた場合は、同梱の scripts/image_gen.py ワークフローを使用してください。単発の SDK 実行用スクリプトは作成しないでください。
• scripts/image_gen.py は絶対に変更しないでください。何か不足している場合は、ほかの作業に進む前にユーザーに確認してください。

組み込みモードの保存先ポリシー：

• 組み込みツールモードでは、Codex はデフォルトで生成した画像を $CODEX_HOME/* に保存します。
• OS の一時ディレクトリを、組み込みモードのデフォルト保存先として説明したり、利用を前提にしたりしないでください。
• 組み込みの image_gen ツールに保存先を指定する引数がある場合でも、その引数について説明したり、利用を前提にしたりしないでください。特定の場所に保存する必要がある場合は、まず画像を生成し、その後、選んだ出力を $CODEX_HOME/generated_images/... から移動またはコピーしてください。
• 組み込みモードでの保存先の優先順位：
  1. ユーザーが保存先を指定した場合は、選んだ出力をそこへ移動またはコピーします。
  2. 画像を現在のプロジェクトで使用する場合は、完了前に、最終的に選んだ画像をワークスペース内へ移動またはコピーします。
  3. 画像がプレビューやアイデア出しのみを目的とする場合は、インラインで表示します。元のファイルはデフォルトの $CODEX_HOME/* の場所に置いたままで構いません。
• プロジェクトから参照される素材を、デフォルトの $CODEX_HOME/* の場所だけに置いたままにしないでください。
• ユーザーが置き換えを明示的に求めていない限り、既存の素材を上書きしないでください。代わりに、hero-v2.png や item-icon-edited.png のような、同じ場所にバージョンを付けたファイル名を作成してください。

両方のモードで共通のプロンプトガイダンスは、references/prompting.md と references/sample-prompts.md にあります。

CLI モード専用のフォールバック用ドキュメント／リソース：

• references/cli.md
• references/image-api.md
• references/codex-network.md
• scripts/image_gen.py

使用する場合

• 新しい画像（コンセプトアート、製品写真、表紙、ウェブサイトのヒーロー画像など）を生成する
• スタイル、構図、雰囲気の参考となる画像を 1 枚以上使って、新しい画像を生成する
• 既存の画像を編集する（インペインティング、照明や天候の変換、背景の置き換え、オブジェクトの削除、合成、背景の透過など）
• 1 つのタスク向けに複数の素材やバリエーションを作成する

使用しない場合

• リポジトリ内の既存の SVG／ベクターアイコンセット、ロゴシステム、イラストライブラリを拡張したり、それらに合わせたりする場合
• SVG、HTML/CSS、canvas で直接作成するのが適切な、単純な図形、図、ワイヤーフレーム、アイコンを作成する場合
• 元ファイルが編集可能なネイティブ形式ですでに存在する、小規模なプロジェクト内素材の編集を行う場合
• 生成されたビットマップではなく、コードで決定論的に出力することをユーザーが明確に求めているタスクの場合

判断ツリー

次の2つの質問を分けて考えてください。

1. 意図： 新しい画像の生成ですか、それとも既存画像の編集ですか？
2. 実行方法： 1つのアセットですか、それとも複数のアセット／バリエーションですか？

意図：

• ユーザーが既存画像の一部を保持したまま変更したい場合は、リクエストを編集として扱います。
• ユーザーが画像をスタイル、構図、雰囲気、被写体の参考としてのみ提供している場合は、リクエストを生成として扱います。
• ユーザーが画像を提供していない場合は、リクエストを生成として扱います。

組み込み編集の仕様：

• 組み込み編集モードは、添付画像やスレッド内で以前に生成された画像など、会話コンテキストですでに表示されている画像を対象とします。
• ユーザーが組み込みツールでローカル画像ファイルを編集したい場合は、まず組み込みのview_imageツールで読み込んで画像を会話コンテキストに表示してから、組み込みの編集フローに進みます。
• 組み込みツールで任意のファイルシステムパスを指定して編集できるとは約束しないでください。
• ローカルファイルを直接編集するためにファイルパスの指定、マスク、その他の明示的なCLI専用パラメーターが引き続き必要な場合は、ユーザーが希望したときに限り、明示的なCLIの代替手段を使用します。
• 編集では、変更してはいけない要素を厳密に保持し、デフォルトでは非破壊的に保存します。

実行方法：

• 組み込みのデフォルトの方法では、リクエストされたアセットまたはバリエーションごとにimage_genを1回呼び出し、複数のアセットまたはバリエーションを作成します。
• 明示的なCLIの代替方法では、ユーザーがCLIモードを明示的に選択し、複数のプロンプト／アセットを必要としている場合に限り、CLIのgenerate-batchサブコマンドを使用します。

ユーザーが既存の画像を変更するよう明確に求めていない限り、新しい画像を作成したいものと想定してください。

ワークフロー

1. 最上位のモードを決定します。デフォルトでは組み込みを使用し、明示的に求められた場合にのみ CLI にフォールバックします。
2. 意図を決定します。generate または edit です。
3. 出力がプレビュー専用か、現在のプロジェクトで使用するものかを決定します。
4. 実行方法を決定します。単一アセット、組み込みツールの繰り返し呼び出し、または CLI の generate-batch のいずれかです。
5. 入力を事前にすべて集めます。プロンプト、正確なテキスト（原文どおり）、制約・除外リスト、入力画像を用意します。
6. 各入力画像の役割を明示的に指定します。
   • 参照画像
   • 編集対象
   • 補助的な挿入・スタイル・合成用の入力
7. 編集対象がローカルファイルシステム上にのみあり、組み込みの方法を使用する場合は、まず view_image で確認し、会話のコンテキストで画像を利用できるようにします。
8. 写真、イラスト、スプライト、製品画像、バナー、またはその他の明示的にラスター形式のアセットをユーザーが求めた場合は、SVG／HTML／CSS のプレースホルダーで代用せず、image_gen を使用します。既存のリポジトリにある SVG／ベクター／コードのアセットに合わせる必要があるアイコン、ロゴ、UI グラフィックの場合は、代わりにそれらを直接編集することを優先します。
9. 具体性に応じてプロンプトを補足します。
   • ユーザーのプロンプトがすでに具体的で詳細な場合は、創作上の要件を追加せず、明確な仕様に整えます。
   • ユーザーのプロンプトが一般的な場合は、出力品質を実質的に高める場合に限り、適切な補足を加えます。
10. デフォルトでは組み込みの image_gen ツールを使用します。
11. ユーザーが CLI へのフォールバックを明示的に選択した場合に限り、品質、input_fidelity、マスク、出力形式、出力パス、ネットワーク設定について、フォールバック専用のドキュメントを使用します。
12. 出力を確認して検証します。被写体、スタイル、構図、テキストの正確さ、不変条件・除外項目を確認します。
13. 変更を一度に一つだけ加えて反復し、その後もう一度確認します。
14. プレビュー専用の作業では、画像をインラインで表示します。元のファイルはデフォルトの $CODEX_HOME/generated_images/... パスに残してもかまいません。
15. プロジェクトで使用する作業では、選択したアセットをワークスペースに移動またはコピーし、それを使用するコードや参照を更新します。プロジェクトで参照されるアセットをデフォルトの $CODEX_HOME/generated_images/... パスに残してはいけません。
16. バッチ処理では、破棄したバリエーションも保持するよう明示的に求められた場合を除き、選択した最終成果物のみをワークスペースに保存します。
17. ワークスペースで使用するアセットについては、最終保存パスに加え、最終プロンプト、および組み込みツールとフォールバックの CLI モードのどちらを使用したかを必ず報告します。

プロンプトの補足

ユーザーのプロンプトを、構造化された実用的な仕様に整えます。ユーザーの目標をより明確で実行しやすくしますが、詳細をむやみに追加してはいけません。

これはプロンプトを整えるための指針であり、固定されたスキーマではありません。役立つ項目だけを使用し、明確さが実質的に向上する場合は、ラベル付きの短い項目を追加します。

具体性に関する方針

どの程度補足するかは、ユーザーのプロンプトの具体性に応じて判断します。

• プロンプトがすでに具体的で詳細な場合は、その具体性を保ち、構造を整えるだけにします。
• プロンプトが一般的な場合は、出力の質を実質的に高めるときに限り、適切な補足を加えてもかまいません。

許可される補足：

• 構図やフレーミングに関するヒント
• 仕上がりの品質や想定用途に関するヒント
• 実用的なレイアウトの指針
• 示された依頼を補う、妥当で具体的な場面設定

許可されない補足：

• 依頼から示唆されていないキャラクターや物体の追加
• 依頼から示唆されていないブランド名、スローガン、配色、物語の展開
• 周囲のレイアウトによる裏付けのない、任意の左右の配置指定

ユースケースの分類（スラッグは変更しないでください）

各リクエストを以下のいずれかに分類し、プロンプトや参照箇所でスラッグを一貫して使用してください。

生成：

• photorealistic-natural — 実際の質感と自然光を生かした、日常や編集記事向けの自然なシーン。
• product-mockup — 商品やパッケージの撮影画像、カタログ画像、グッズのコンセプト。
• ui-mockup — アプリやウェブのインターフェースのモックアップ、ワイヤーフレーム。求める忠実度を指定してください。
• infographic-diagram — 構造化されたレイアウトとテキストを含む図やインフォグラフィック。
• logo-brand — ロゴやマークの検討。ベクター形式に適したもの。
• illustration-story — 漫画、児童書のアート、物語性のあるシーン。
• stylized-concept — スタイルを重視したコンセプトアート、3D／スタイライズドレンダリング。
• historical-scene — 時代考証や世界に関する知識に沿ったシーン。

編集：

• text-localization — 画像内のテキストを翻訳・置換し、レイアウトを維持する。
• identity-preserve — 試着合成や人物のシーンへの追加。顔、体、ポーズを固定する。
• precise-object-edit — 特定の要素を削除・置換する（室内の差し替えを含む）。
• lighting-weather — 時刻、季節、雰囲気のみを変更する。
• background-extraction — 背景を透過させる／きれいに切り抜く。
• style-transfer — 被写体やシーンを変えながら、参照スタイルを適用する。
• compositing — 複数の画像を、光と遠近感を合わせて挿入・合成する。
• sketch-to-render — 描画や線画をフォトリアルなレンダリングにする。

共通プロンプトスキーマ

以下のラベル付き仕様を、両方のトップレベルモードで共通のプロンプトのひな形として使用してください。

Use case: <taxonomy slug>
Asset type: <where the asset will be used>
Primary request: <user's main prompt>
Input images: <Image 1: role; Image 2: role> (optional)
Scene/backdrop: <environment>
Subject: <main subject>
Style/medium: <photo/illustration/3D/etc>
Composition/framing: <wide/close/top-down; placement>
Lighting/mood: <lighting + mood>
Color palette: <palette notes>
Materials/textures: <surface details>
Text (verbatim): "<exact text>"
Constraints: <must keep/must avoid>
Avoid: <negative constraints>

注意：

• Asset type と Input images はプロンプトのひな形であり、専用の CLI フラグではありません。
• Scene/backdrop は視覚的な設定を指します。出力の透過動作を制御するフォールバック CLI の background パラメーターとは異なります。
• Quality:、Input fidelity:、マスク、出力形式、出力パスなど、フォールバックでのみ使う実行上の注意事項は、明示的な CLI の手順にのみ記載してください。これらを組み込みの image_gen ツールの引数として扱わないでください。

拡張ルール：

• 簡潔にしてください。
• プロンプトを実質的に改善するために必要な詳細だけを追加してください。
• 編集では、不変条件を明示的に列挙してください（「X のみ変更し、Y は変更しない」）。
• 成功に不可欠な詳細が不足していて作業を進められない場合は、質問してください。それ以外の場合は、そのまま進めてください。

例

生成例（ヒーロー画像）

Use case: product-mockup
Asset type: landing page hero
Primary request: a minimal hero image of a ceramic coffee mug
Style/medium: clean product photography
Composition/framing: wide composition with usable negative space for page copy if needed
Lighting/mood: soft studio lighting
Constraints: no logos, no text, no watermark

編集例（不変条件）

Use case: precise-object-edit
Asset type: product photo background replacement
Primary request: replace only the background with a warm sunset gradient
Constraints: change only the background; keep the product and its edges unchanged; no text; no watermark

プロンプト作成のベストプラクティス

• プロンプトは、シーン／背景 → 被写体 → 詳細 → 制約の順に構成してください。
• 想定用途（広告、UI モックアップ、インフォグラフィック）を含め、モードと仕上がりのレベルを設定してください。
• フォトリアリズムには、カメラや構図に関する表現を使ってください。
• ユーザーがベクター出力や画像ではないプレースホルダーを明示的に求めた場合に限り、SVG／ベクターの代替表現を使用してください。
• 正確なテキストを引用し、タイポグラフィと配置を指定してください。
• 読み間違えやすい単語は、文字を一つずつ綴り、原文どおりに描画するよう指定してください。
• 複数の画像を入力する場合は、インデックスで画像を参照し、それぞれの使用方法を説明してください。
• 編集では、変更によるずれを抑えるため、反復のたびに不変条件を繰り返してください。
• 変更を一つずつ指定して反復してください。
• プロンプトが汎用的な場合は、実質的に役立つ詳細だけを追加してください。
• プロンプトにすでに詳細がある場合は、内容を増やすのではなく整えてください。
• 明示的な CLI フォールバックに限り、quality、input_fidelity、マスク、出力形式、出力パスのガイダンスについては、references/cli.md と references/image-api.md を参照してください。

両方のモードに共通するその他の原則：references/prompting.md。 両方のモードで共通するコピー＆ペースト用仕様：references/sample-prompts.md。

アセットタイプ別のガイダンス

アセットタイプ別のテンプレート（ウェブサイト用アセット、ゲーム用アセット、ワイヤーフレーム、ロゴ）は、references/sample-prompts.md にまとめられています。

フォールバック CLI モードのみ

一時ファイルと出力の規則

これらの規則は、明示的な CLI フォールバックにのみ適用されます。組み込みの image_gen の出力動作について説明するものではありません。

• 中間ファイル（JSONL バッチなど）には tmp/imagegen/ を使用し、完了後に削除してください。
• 最終成果物は output/imagegen/ に保存してください。
• 出力パスの指定には --out または --out-dir を使用してください。ファイル名は一貫性のある分かりやすいものにしてください。

依存関係

このリポジトリでは、依存関係の管理に uv を使用することをおすすめします。

必須の Python パッケージ：

uv pip install openai

画像の縮小にのみ必要なオプションパッケージ：

uv pip install pillow

移植性に関する注意：

• インストール済みのスキルをこのリポジトリの外で使用する場合は、その環境のパッケージマネージャーで依存関係をインストールしてください。
• uv で管理されている環境では、uv pip install ... を引き続き推奨します。

環境

• ライブ API 呼び出しには OPENAI_API_KEY を設定する必要があります。
• 組み込みの image_gen ツールを使用する場合、ユーザーに OPENAI_API_KEY を尋ねないでください。
• チャットでキー全体を貼り付けるようユーザーに求めないでください。ローカルで設定してもらい、準備ができたことを確認してください。

キーが設定されていない場合は、次の手順を案内してください：

1. OpenAI プラットフォームの UI で API キーを作成します：https://platform.openai.com/api-keys
2. システムの環境変数として OPENAI_API_KEY を設定します。
3. 必要に応じて、ユーザーの OS／シェルで環境変数を設定する方法を案内します。

この環境でインストールできない場合は、不足している依存関係と、アクティブな環境にインストールする方法をユーザーに伝えてください。

スクリプトモードに関する注意

• CLI コマンドと使用例：references/cli.md
• API パラメーターのクイックリファレンス：references/image-api.md
• CLI モードのネットワーク承認／サンドボックス設定：references/codex-network.md

リファレンスマップ

• references/prompting.md：両方のモードで共通するプロンプト作成の原則。
• references/sample-prompts.md：両方のモードで共通する、コピーして使えるプロンプトのレシピ。
• references/cli.md：フォールバック専用の CLI 使用方法。scripts/image_gen.py を使用します。
• references/image-api.md：フォールバック専用の API／CLI パラメーターリファレンス。
• references/codex-network.md：フォールバック専用の、CLI モードにおけるネットワーク／サンドボックスのトラブルシューティング。
• scripts/image_gen.py：フォールバック専用の CLI 実装。ユーザーが明示的に CLI モードを選択しない限り、読み込んだり使用したりしないでください。