pixeltamer

pixeltamer — GPT Image 2.5 で画像を生成、編集、合成

指示どおりに画像を生成します。どちらか一方を選ぶ必要がないよう、2 つのバックエンドを用意しています。OpenAI API キーを使うか、ChatGPT サブスクリプションにサインイン済みの codex CLI を使えます。API バックエンドのデフォルトは gpt-image-2.5-flare で、--model を指定できます。Codex はサーバー側で画像モデルを選択します。同じスキル、同じプロンプトで、支払い方法を選べます。

このスキルを使う場面

次のような依頼があった場合に、このスキルを使います。

• 新しい画像、ポスター、イラスト、写真、モックアップ、アイコン、ステッカー、スプライト、ロゴ、ヒーロー画像、インフォグラフィック、広告クリエイティブ、スクロールを止めるカード、雑誌の表紙、ポッドキャストアート、商品写真、バナー、OG 画像、ソーシャルカード、キャラクター設定シート、アプリ画面、ダッシュボードのモックアップ
• 既存の画像の編集（変更、インペイント、マスク、特定の要素だけを変更）
• 複数の参照画像を 1 つにまとめる合成
• 検証を行いながら、関連する画像をまとめて生成するバッチ処理

「画像を作って」など、画像の生成を求める依頼には、このスキルを使います。

前提条件 — インストールを確認する（最初の生成の前に実行）

まず、利用できるものを確認します。

pixeltamer doctor

出力に ✓ マーカー付きのバックエンドが 1 つ以上あれば、準備完了です。画像を生成してください。自動検出では、キーが設定されていれば API、設定されていなければ codex が選ばれます。呼び出しごとに --backend api|codex で上書きするか、環境変数 PIXELTAMER_BACKEND を設定してください。

**pixeltamer doctor を実行すると、バックエンドの状態が表示されず permission denied で失敗する場合：**インストール／アップデート時に skills CLI がディスパッチャーの実行権限を削除しています。ディスパッチャーは、自分の実行権限を復元する処理を実行できないため、まず bash 経由で一度起動してください。以降はほかの問題も自動修復されます。

# run it through bash (works even without +x):
bash ~/.claude/skills/pixeltamer/scripts/pixeltamer doctor
# or restore the bit permanently:
chmod +x ~/.claude/skills/pixeltamer/scripts/pixeltamer

ほかのスクリプトはすべてインタープリター経由で実行されるため、この権限の影響を受ける可能性があるファイルはディスパッチャーだけです。

両方のバックエンドに ✗ が表示された場合、pixeltamer config は実行しないでください。実際の TTY を必要とする対話型プロンプトですが、Bash ツールには TTY がないため、呼び出しが永久に停止します。代わりに AskUserQuestion を使い、次の選択肢をユーザーに提示してください。

"Pixeltamer を使うには、2 つのバックエンドのうち 1 つが必要です。選択してください： API キー — 最速で、全機能（編集＋合成）を利用できます。画像ごとに料金が発生します。 Codex CLI — 既存の ChatGPT Plus／Team／Enterprise サブスクリプションを利用します。キーは不要で、生成のみ可能です。"

ユーザーが API を選んだ場合

pixeltamer の設定ディレクトリにキーを保存するよう伝えてください。Python スクリプトが呼び出しのたびに自動で読み込むため、シェルの再起動や環境変数の管理が不要な、最も簡単な方法です。

mkdir -p ~/.config/pixeltamer
echo 'OPENAI_IMAGE_API_KEY=sk-yourkeyhere' > ~/.config/pixeltamer/.env
chmod 600 ~/.config/pixeltamer/.env

ユーザーの組織で GPT Image の利用確認が済んでいない場合、最初の呼び出しでは 403 が返されます。一度だけ必要な確認について、https://platform.openai.com/settings/organization/general を案内してください。

代わりに dotfiles を使う場合は、~/.zshrc（または .bashrc）に export OPENAI_API_KEY="sk-..." を設定する方法もあります。ただし、新しい環境変数を継承させるため、エージェントを再起動する必要があります。.env ファイルを使う場合は再起動不要です。

ユーザーが codex を選んだ場合

# 1. install codex if missing
npm install -g @openai/codex

# 2. log in (opens a browser, OAuth via ChatGPT)
codex login

# 3. confirm
codex login status

再起動は不要です。bash バックエンドは、呼び出しのたびに codex の認証情報を新たに読み込みます。

codex はスキルとは別に更新されます。npx skills update では更新されません。pixeltamer doctor はインストール済みの codex のバージョンを報告し、npm の最新バージョンより古い場合は警告するようになりました（古い codex は既知の失敗要因です。以前、古いスキーマバージョンが原因で処理が無期限に停止したことがあります）。doctor がアップデートを知らせたら、npm install -g @openai/codex@latest を実行してください。

ユーザーが設定を終えたら

pixeltamer doctor を再実行して確認します。その後、元の依頼に進んでください。

3 つのモード

モード 1 — 1 回限りの生成

pixeltamer generate -p "<prompt>" --size 1024x1024 --quality high -o output.png

generate を自動で補うショートカットもあります。

pixeltamer "Create a pitch-deck slide titled..."

試しに生成する場合は、4 つを並行して実行します。

pixeltamer generate -p "..." -n 4 --concurrency 4 -o variants/

透明なアセット

自分で制御できない背景に合成するもの（アイコン、ロゴ、マスコット、商品写真、グラフのレイヤー、ステッカーなど）は、後からグリーンバックを除去するのではなく、実際のアルファチャンネル付きで生成してください。

pixeltamer generate -p "<isolated subject>" --background transparent -o asset.png

generate の両方のバックエンドで動作します。API ではリクエストパラメーターとして指定し、codex ではプロンプトの指示に変換されます（codex には背景パラメーターがありません）。さらに、PNG が RGB で返された場合は、アルファチャンネルを自動でチェックし、stderr に警告を出します。Codex の edit／compose では対応できません。その場合はディスパッチャーがその旨を伝えます。

プロンプトを書く前に知っておくべき注意点は、フラグよりプロンプトが優先されることです。背景、面、シーン、または落ち影を指定すると、それらが描画され、どこにもエラーが出ないまま完全に不透明な PNG が生成されます。制約ブロックと検証手順については、references/transparency.md を読み込んでください。

モード 2 — 編集／インペイント

# Modify a single existing image
pixeltamer edit -i source.png -p "Change ONLY the sky to overcast. Preserve everything else exactly." -o edited.png

# With a mask — white pixels regenerate
pixeltamer edit -i source.png --mask mask.png -p "..." -o edited.png

編集は両方のバックエンドで動作します。API の処理では /v1/images/edits を使用します（領域ベースのインペイント用に --mask をサポートします）。codex の処理では OAuth Responses API を直接使用します（scripts/pixeltamer_codex_oauth.py）。認証情報は codex exec と同じ ChatGPT のものを使いますが、トランスポートは異なり、API キーは不要です。Codex-OAuth は --mask をサポートしていません。マスクベースのインペイントが必要な場合は、API の処理を使用してください。

モード 3 — 複数の参照画像を使った合成

2～16 枚の参照画像を渡して、/images/edits 経由で 1 枚の出力画像に合成します。

pixeltamer compose \
  -p "Reference 1 is the product. Reference 2 is the kitchen scene. Compose: place the product on the counter with morning window light from the left." \
  -i product.png \
  -i kitchen.png \
  -o composed.png \
  --size 1536x1024

これは画期的な機能です。実際に機能するラベル付けのパターンについては、references/multi-reference.md を参照してください。

参照画像の順番は引き続き重要です。失いたくない顔、ロゴ、または商品のディテールを最初に配置してください。GPT Image 2.5 では、デフォルトで被写体の保持性能が向上しています。--input-fidelity high は、この制御を公開しているモデルやホストで、API を直接使った編集時に引き続き利用できます。

モード 4 — バッチ（検証付きの複数画像プラン）

4 枚以上の関連画像（ウェブサイトのヒーロー画像、特徴紹介、フッター、ソーシャルメディア用画像など）が必要なプロジェクトでは、バッチ状態機械を使用します。ワークフローは次のとおりです。

1. 必要な画像を調査します。
2. 画像ごとにエントリーを 1 つ記載した prompts.md を作成します（出力先パス、形式、ネイティブサイズ、任意の参照画像、ステータス、プロンプト）。 Format に PNG transparent と記載されたエントリーは、--background transparent を指定して生成する必要があります。検証ツールは実際のアルファチャンネルをチェックし、なければ失敗と判定します。 バッチが「コレクション」（商品シリーズ、アイコンファミリー、ステッカーパックなど）の場合、共通のスタイルおよび制約ブロックを 1 つ作成し、各エントリーのプロンプトにそのまま追加します。この共通の末尾部分によって、N 枚の画像を個別に生成しても 1 つのセットとして統一感が生まれます。詳細は references/transparency.md を参照してください。
3. 各画像を生成し、エントリーごとに適切なバックエンドを呼び出します。
4. pixeltamer batch <path-to-prompts.md> を実行して、すべての出力を検証します（ファイルの存在、寸法の一致、ファイルサイズが妥当かどうか）。
5. Read ツールを使って、生成された各 PNG を目視で自己レビューします。プロンプトと一致しない場合は、ステータスを failed:<reason> に変更します。
6. 失敗したエントリーだけを再生成します。

prompts.md の形式は scripts/verify-images.mjs の検証ツールで解析されます。構成については、references/multi-reference.md を参照してください。

ワークフロー — 呼び出されたときの手順

0. まず references/index.md を読みます。 ルーティングマップで、リクエストに最も近いものを探します。必要最小限の範囲だけを読み込みます。レシピまたはプレイブックファイルを1つ、あるいはリファレンスを1つに絞り、すべてを読み込まないでください。レシピやプレイブックに似たパターンがある場合、プロンプトを一から作成しないでください。一致するものがない場合は、references/prompting.md と最も近いレシピを使用します。
1. リクエストを理解します。 モード（生成／編集／合成／バッチ）を特定します。ステップ0で読み込んだレシピ／プレイブック／リファレンスが実際に適合しているか確認し、適合しない場合はルーティングし直します。
2. 必要に応じてリファレンスを読みます。 index.md が示したファイルに加え、複雑なプロンプトを扱う場合は references/prompting.md を読み込みます。合成モードでは references/multi-reference.md を読み込みます。透過アルファを使うアセットでは references/transparency.md を読み込みます。プログラムでプロンプトを組み立てる場合、ドクトリンのカテゴリー（UI／インフォグラフィック／ブランドアイデンティティ／Eコマースのヒーロー画像／建築レンダリング／科学アトラス／タイポグラフィポスター）のいずれかに該当する場合、または多数の画像でブランドの一貫性が必要な場合は、references/prompt-patterns.md を読み込みます。すべてのリファレンスをコンテキストに読み込むのではなく、必要なものだけを取り込みます。
3. 指定されていないパラメーターを決めます。 用途に応じて適切なサイズを選びます（references/prompting.md のサイズ表を参照）。--quality high をデフォルトにします。ユーザーがバックエンドを指定していない場合は、バックエンドを選びます。アセットを別のものに合成する場合（アイコン、ロゴ、マスコット、切り抜き、チャートのレイヤーなど）は、--background transparent を指定し、プロンプトを書く前に references/transparency.md を読み込みます。
4. プロンプトを作成します。 標準の構成を適用します。意図 → シーン → 被写体 → 詳細 → テキスト → スタイル → 制約。「8K、超詳細、傑作、プロフェッショナル」などの魔法の言葉は削除します。画像内に表示するテキストは引用符で囲みます。編集時は、保持する要素を指定します。UI画面、インフォグラフィック、ブランドのレンダリング、科学アトラス、またはプログラムでプロンプトを組み立てるリクエストでは、JSON設定スキーマと、references/prompt-patterns.md にあるその他の高度なパターンを使います。
5. 生成します。 適切な pixeltamer サブコマンドを呼び出します。生成された絶対パスを表示します。
6. 目視で自己検証します。 Read ツールを使って、生成された PNG を確認します。プロンプトと照らし合わせて評価します。
   • 被写体は一致していますか？
   • テキストは正しく描画され、引用したとおりに正確に綴られていますか？
   • 明らかな不具合（ゆがんだ人体、スペルミス、文字の乱れ）はありませんか？
   • 構図は依頼どおりですか？
   • 透過を指定した場合、アルファは実際に透過していますか？不透明なアルファチャンネルは、よくある見落とされがちな失敗です。推測せず、確認してください。 失敗している場合は、正直に伝えます。悪い結果を「素晴らしい見た目です！」とごまかさないでください。
7. 反復するか、引き渡します。 結果が間違っている場合は、1回の再生成につき変更する要素を1つに絞ります（references/prompting.md の反復表を参照）。結果が良好な場合は、ファイルパスをユーザーに提示します。

フラグでプロパティを制御し、プロンプトで内容を指定します

このスキル全体で最もすっきりした考え方であり、エージェントが最もよく誤解する点です。出力のプロパティはフラグで制御します。プロンプトで説明しても、確実ではなく、バックエンドによって挙動が異なります。

プロパティ	フラグを使用	プロンプトでは指定しない
寸法	--size 1536x1024、2K、4K	「1536x1024 の画像で…」
出力コンテナー	--output-format png|jpeg|webp	「webp として保存」
圧縮	--output-compression 0-100	「少し圧縮して」
レンダリング品質	--quality low|medium|high	「高品質で、精細に」
バリエーション数	-n 4	「4 つのバージョンをください」
編集領域	--mask region.png	「左上だけ変更して」
参照画像への忠実度	GPT Image 2.5：重要な参照画像を最初に指定。旧モデル：--input-fidelity high	「顔をまったく変えないで」

プロンプトでは、画像の中に何があるかを指定します。サイズ、形式、枚数、マスクは画像の中にはありません。

背景は例外で、codex の場合に限ります。 API バックエンドでは、--background は実際のパラメーターなので、上記のルールが当てはまります。codex にはそのようなパラメーターがないため、透明度は本当にプロンプトで指定します。そのため、--background transparent はフラグを設定するのではなく、プロンプトを書き換えます。どちらの情報も references/transparency.md に記載されています。

視覚的な自己検証 — 必須

生成した画像はすべて Read で読み込み直し、成功を報告する前に目視で評価します。画像生成は確率的な処理です。「API 呼び出しに成功した」からといって、「依頼どおりの画像になった」とは限りません。この手順では、次のような問題を見つけられます。

• 画像内のテキストの誤字や言い換え
• 被写体の誤り（コーヒーカップではなくコーヒーショップ）
• 視覚的なアーティファクト（歪んだ手、文字の乱れ、余分な手足）
• アスペクト比に合わない構図（被写体が小さすぎる、または切れている）
• ブランドイメージに合わない色やトーン

問題がある場合は、たいてい、改善を期待して新しい句を 3 つ追加するのではなく、プロンプトの 1 か所だけを変えて再生成するのが適切です。

出力形式 — ユーザーへの伝え方

生成に成功したら、次の情報を提示します。

• 絶対パス（スクリプトが標準出力に表示します）
• 生成内容を説明する一文（例：「見出しを正確に描画した 1024×1536 の縦長カバーを生成しました」）
• 複数のバリエーション（-n N）がある場合は、すべてのパス

自己検証で失敗が確認された後は、次のようにします。

• 問題の内容を説明します（テキストが言い換えられた、被写体が一般的すぎた、など）。
• 最も可能性の高い修正を 1 つ提案し、再生成するか尋ねます。
• ユーザーの了承なしに自動で再生成しないでください。ユーザー自身でプロンプトを調整したい場合があります。

利用可能なレシピ

recipes/infographic.md · recipes/meta-ad.md · recipes/viral-linkedin.md · recipes/ui-mockup.md · recipes/editorial-cover.md · recipes/product-photo.md · recipes/mascot.md

該当するトリガーに合うレシピを読み込みます。各レシピには、プロンプトのひな形、作成例、サイズのデフォルト値、よくある失敗の一覧が記載されています。

マスコット／ブランドキャラクター／アプリアイコンのキャラクターに関する依頼では、プロンプトを書く前に必ず recipes/mascot.md を読み込みます。 「かわいいキャラクター」に対するモデルのデフォルトは、ありきたりな Slack の blob です。このレシピには、文脈に応じてアンカーを選ぶ判断ツリー、シルエットとスケールのルール、避けるべきパターンを抑制するための明示的な指示がまとめられています。これを省略するのは、平凡なマスコットになる最もよくある原因です。

利用可能なリファレンス

references/prompting.md — 基本方針。標準的な構成、避けるべき指示、スタイル／構図／照明の用語。 references/api-backend.md — API 固有の情報、環境変数、トラブルシューティング。 references/codex-backend.md — codex CLI 固有の情報、2 種類の呼び出しパターン、トレードオフ。 references/multi-reference.md — compose モードの使いこなし、ラベル付けのパターン、参照画像セットのサイズ。 references/post-process.md — 圧縮、サイズ変更、形式変換、アルファチャンネルの抽出、結合。 references/ui-mockup-prompting.md — 類推スタイルと一覧スタイル、プレースホルダーより実データを優先する方法、アセットの体系化。

現在の作業に必要なものだけを参照します。すべてを一度に提示しないでください。

よくある間違い — こうしたパターンは避けましょう

避けること	理由
「8K、超高精細、傑作、artstationで話題」	魔法の言葉では、視覚的な仕上がりを指定できません。代わりに、素材、光、構図、質感を説明してください。
「プロフェッショナル、美しい、高級、圧巻」	指示内容がまったくない、称賛の言葉です。
利用可能なバックエンドを確認する前に生成する	このセッションで初めて呼び出す場合は、まず pixeltamer doctor を実行してください。
codex バックエンドで編集／合成する	OAuth Responses API（pixeltamer_codex_oauth.py）経由で、0.3.0 以降は動作します。マスクベースのインペインティングには、引き続き API パスが必要です。Responses API はマスクパラメーターを受け付けないためです。特定の出力サイズが必要な編集も同様です。codex は入力のアスペクト比を維持し、--size を無視します。
切り抜き素材にクロマキー用の緑色背景を使う	古い方法です。--background transparent を指定すれば、generate ではどちらのバックエンドでも実際のアルファチャンネルが得られます。エッジが汚くなった場合、または codex の edit／compose の場合にのみ、クロマキーを使ってください。
透明背景を求めながら、背景を説明する	プロンプトはフラグより優先されます。「清潔感のある白いスタジオ」と指定すると、--background transparent より優先され、白い四角形になります。
目視での自己検証を省略する	画像生成は確率的です。「API が成功した」ことは「画像が正しい」ことを意味しません。
うまくいかないとき、一度に新しい条件を3つ追加する	一度に変更するのは1つの要素だけにしてください。そうしないと、何が効果的だったのかわかりません。
examples フォルダーの PNG を正解とみなす	これらはデモであり、仕様ではありません。再生成時には構図が変わります。

バックエンド早見表

目的	使用するもの
最速で画像を1枚生成する	デフォルトの gpt-image-2.5-flare を使った API
API キーを持っていない／使いたくない	codex
既存の画像を編集する（マスクなし）	どちらのバックエンドでも可 — API または codex-OAuth
マスクベースのインペインティング	API のみ — Responses API はマスクパラメーターを受け付けません
編集後も顔／ロゴ／ラベルの文字を保持する	API。Sunburst を使い、重要な参照画像を最初に配置してください
編集時に出力サイズを確実に指定する	API のみ — codex は edit／compose で --size を無視し、入力のアスペクト比を維持します
参照画像を2～16枚合成する	どちらのバックエンドでも可 — API または codex-OAuth
認証情報を共有せずにチームメイトのマシンで実行する	codex（各ユーザーが個別にサインインします）
透明な背景／実際のアルファチャンネル	generate では両方。API ではパラメーターで指定し、codex ではプロンプトで指定して確認します。codex の edit／compose では API のみ
特定の出力ファイル形式（png／jpeg／webp）	--output-format を使う API のみ — codex のどちらのトランスポートも、常に PNG を返します
OpenAI 互換のカスタムホスト（jmrai、ZenMux、OpenRouter）	OPENAI_IMAGE_BASE_URL を設定した API
最高品質／編集精度	OPENAI_IMAGE_MODEL=gpt-image-2.5-sunburst を設定した API
高品質で最大サイズ（4K）	API。codex では generate の場合のみ --size が反映され、大きな出力では推論ループが遅くなります

ペルソナに関する注意

出力（ファイルパス、成功メッセージ、失敗の説明）は簡潔で実用的なものにしてください。誇張した表現や、「圧巻の傑作が生成されました」といった言い回しは不要です。pixeltamer がなくそうとしているのは、まさにそうした粗雑な表現であり、生成することではありません。生成したもの、その保存場所、次に行うことだけを伝えてください。