picgen

PicGen スキル

PicGen は、エージェントのワークフローをユーザーが設定した画像生成プロバイダーに接続します。外部の画像プラットフォームにプロンプトをコピーせず、エージェントとの会話の中で画像を生成したい、技術に詳しくないユーザー向けに設計されています。

呼び出しポリシー

ユーザーが画像の生成、作成、レンダリング、出力を明示的に依頼した場合、または PicGen の名前を明示的に挙げた場合は、PicGen を使用します。

ユーザーが視覚的な出力を強く求めているものの、今すぐ生成するよう明確に依頼していない場合は、PicGen のワークフローを開始する前に確認します。

ユーザーが視覚的な方向性、雰囲気、ブランドスタイル、抽象的なビジュアルのアイデアについて話していて、出力を求めていない場合に限り、PicGen を提案します。

ユーザーのクォータを黙って消費してはいけません。デフォルトでは会話のコンテキスト全体をプロバイダーに送信せず、最終プロンプトに必要な視覚的な詳細だけを要約します。

インストール

picgen が利用できない場合は、まず CLI をインストールします。

npm install -g @ai-agent-tools/picgen@latest

対応するエージェント向けにこのスキルをインストールまたは更新するには、標準の Skills インストーラーを優先します。

npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy

Codex の場合に限り、CLI から直接インストールする方法も利用できます。

picgen skill install codex --force

スキルのインストールまたは更新後、エージェントがスキルを認識するまで、エージェントの再起動または新しいセッションの開始が必要になる場合があります。

アップグレード

ユーザーから PicGen のアップグレードを依頼された場合は、CLI とこのスキルの両方を更新します。npm、スキルのキャッシュ、バージョンの詳細を、技術に詳しくないユーザーに理解してもらう必要はありません。

まず、Node.js と npm が利用可能か確認します。

node -v
npm -v

Node.js または npm が見つからない場合は、まず Node.js LTS をインストールするよう案内します。

CLI をアップグレードします。

npm install -g @ai-agent-tools/picgen@latest
picgen --version
picgen doctor --json

次に、スキルを更新します。

npx -y skills add ai-agent-tools/picgen --skill picgen -g -y --copy

Skills インストーラーが利用できず、使用中のエージェントが Codex の場合は、次を使用します。

picgen skill install codex --force

スキルを更新した後、エージェントが最新の PicGen の指示を再読み込みできるよう、新しい会話を開始するようユーザーに伝えます。新しい会話でも更新したスキルが認識されない場合は、エージェントアプリを再起動するようユーザーに依頼します。

既存のプロバイダーと API キーの設定は保持します。picgen doctor --json が実際の設定上の問題を報告しない限り、アップグレードのためにキーを再設定する必要はありません。

更新の確認

PicGen には更新チェッカーが含まれています。

picgen update check --json

次のタイミングで更新を確認します。

• ユーザーが PicGen のインストール、アップグレード、設定、診断、起動を依頼した場合。
• 参照画像、マスク、ローカル Web UI、プロバイダー管理、履歴など、新しい機能についてユーザーが尋ねた場合。
• オプション、コマンド、プロトコル機能、スキルの指示が利用できないように見えるため、PicGen のコマンドが失敗した場合。
• picgen doctor --json または picgen quickstart が更新のヒントをすでに報告している場合。

画像生成を依頼されるたびに更新を確認してはいけません。更新を提案するためだけに、正常に進んでいる画像生成のワークフローを中断しないでください。

更新がある場合は、コマンドを提示する前に、ユーザーにとっての利点を説明します。機能の向上を中心にした表現を優先します。

PicGen 有新版可用。升级后通常可以直接保留现有渠道和 API key，同时获得新版能力，例如参考图、遮罩编辑、本地网页配置/历史查看，以及更好的 Agent 使用说明。要我帮你现在升级吗？

ユーザーが緊急の画像生成タスクの最中であれば、提案は簡潔にします。

当前版本也可以继续用。我看到 PicGen 有新版，完成这次生成后可以升级，能获得更多生图和配置能力。

ユーザーが同意したら、上記のアップグレードのワークフローに従います。断られた場合は、機能不足で作業を進められない場合を除き、同じ会話でリマインダーを繰り返さず、現在のタスクを続行します。

npm レジストリにアクセスできず更新情報を取得できない場合は、エラーとして扱いません。依頼されたタスクを続行し、ユーザーから明示的に更新確認を依頼された場合にのみ、その旨を伝えます。

環境の確認

CLI のインストール、スキルのインストール、API キーの保存を行う前に、現在のターミナルがユーザーの永続的なローカル環境なのか、サンドボックス／一時的な環境なのかを確認してください。

次のような簡単な確認を行います。

pwd
echo "$HOME"
node -v
npm -v
npm root -g
which picgen || true

環境が永続的なユーザーレベルの環境であると思われる場合は、その環境でセットアップを続行してください。

環境がサンドボックス化されている、リモートである、一時的である、セッション間でリセットされる、またはユーザーの実際のホームディレクトリに書き込めないと思われる場合は、そこで PicGen をインストールしたり、スキルをインストールしたり、API キーを保存したりしないでください。まず、ユーザーのホスト環境／永続的なターミナル、または永続的なユーザーレベルの環境を使用する許可を求めてください。ユーザーに提示する文言の例：

我检测到当前可能是临时沙箱。PicGen 需要安装到你的本机持久环境，否则新会话可能会丢失 CLI、skill 或 API key。请允许我在本机持久环境中继续安装和配置；如果无法授权，我再给你最少的本机终端命令。

許可が得られた場合は、その永続的な環境でインストールとプロバイダーのセットアップを続行してください。許可が得られない場合や拒否された場合は、ユーザーのローカルターミナルで実行できる、最小限のコピー＆ペースト用コマンドを提示してください。手動の手順は短くし、ユーザーが行う必要のあることだけを説明してください。

ローカル Web インターフェース

ユーザーが「PicGen を開いて」「PicGen を開く」「画像生成ツールを開いて」と言った場合、ビジュアル設定ページを求めた場合、CLI コマンドを覚えずに生成したい場合、または以前に生成した画像を探したい場合は、ローカル Web インターフェースを起動してください。

picgen open

出力されたローカル URL をユーザーに返してください。PicGen は 127.0.0.1 にバインドし、デフォルトのポートは 8188 です。必要に応じて次のポートを自動的に試します。サーバーはフォアグラウンドで実行されます。ページを使用している間は、ユーザーまたはエージェントがターミナルを実行したままにし、終了したら Ctrl+C で閉じてください。

現在の環境がサンドボックス化されている、リモートである、または一時的であると思われる場合は、picgen open を実行する前に、ユーザーの永続的なローカル環境へのアクセス許可を求めてください。それが不可能な場合は、ユーザーのローカルターミナルで picgen open を実行し、出力された URL を開くよう、短く指示してください。

ローカルページでは、明示的に表示操作を行った場合に限り、ユーザーのブラウザー内で完全な API キーを表示できます。チャットでは、次のようなマスクされたコマンドだけでキーを確認してください。

picgen key list --json
picgen key show PICGEN_GEMINI_PROXY_KEY --json

ユーザー向けのセットアップ、プロバイダー管理、生成、履歴の閲覧には Web インターフェースを使用してください。エージェント主導のドライラン、自動化、診断、正確で再現可能な手順には CLI コマンドを使用してください。

エージェントが初めてセットアップを支援する場合は、ユーザーが会話を続けられ、UI の切り替えを避けられるため、クリップボードを使った CLI フローを優先してください。ユーザーが複数のプロバイダーを管理したい場合、キーのマスクされた情報源を確認したい場合、ローカルで完全なキーを表示したい場合、CLI コマンドを使わずに画像を生成したい場合、または保存済み画像の履歴を探したい場合は、Web インターフェースを優先してください。

ワークフロー

1. picgen doctor --json を実行して、設定を確認します。
2. 利用可能なプロバイダーが設定されていない場合は、生成する前にプロバイダーを設定します。
3. poster、product-shot、social-cover など、ユーザーの意図に合わせてプリセットを選択します。
4. picgen create --dry-run --preset <preset> "<prompt>" を実行します。
5. ドライランの結果を、ユーザー向けの生成プレビューとして提示します。必要な場合を除き、技術用語としての「ドライラン」は使わないでください。
6. ユーザーの確認後、picgen create --preset <preset> "<prompt>" を実行します。
7. 画像のプレビュー、または保存先のファイルパスを表示します。

ユーザーが直接生成するよう明示した場合、または確認を求めないよう明示した場合は、ユーザー向けの確認手順を省略してもかまいません。それでも、内部では生成計画を立ててください。

デフォルトでは画像を1枚生成します。選択肢を提示するためだけに複数の画像を生成しないでください。ユーザーが複数の選択肢、バリエーション、比較、または具体的な枚数を明示的に求めた場合にのみ、複数の画像を生成します。

ユーザーが枚数、サイズ、アスペクト比、品質、または形式を指定した場合は、1回限りの生成フラグを使用します。これらのフラグは保存済みの設定を変更しません。

picgen create --n 2 --size 1088x576 --quality low "<prompt>"
picgen create --aspect-ratio 16:9 --size medium "<prompt>"

OpenAI 互換プロバイダーでは、PicGen はリクエストを送信する前に、指定された WIDTHxHEIGHT サイズを現在のモデルのルールに適合するよう正規化します。たとえば、元のサイズが現在の最小ピクセル数を下回る場合、1088x576 は 1120x592 として送信されることがあります。プロバイダーが最終的に近いものの異なるピクセルサイズを返す場合もあります。PicGen はプロバイダーの結果をそのまま保存し、画像のサイズ変更、切り抜き、余白追加、引き伸ばしは行いません。

技術に詳しくないユーザーに説明する際は、簡潔に伝えてください。

你指定的尺寸会作为目标尺寸使用。PicGen 会先按模型规则选择一个最接近的合法请求尺寸，最终图片尺寸以模型实际返回为准，不会额外拉伸或裁切。

Gemini プロバイダーでは、PicGen は正確なサイズを、最も近い対応済みの aspectRatio と効率的な imageSize に変換します。一般的なバナーのリクエストでは、通常 1K が使用されます。

プロバイダーの設定

ターミナルのプロンプトがユーザーに表示される場合は、picgen setup を使用してもかまいません。

対話型ターミナルのプロンプトが表示されないエージェント環境で実行する場合は、ブロッキングウィザードとして picgen setup を実行しないでください。ユーザーに次の情報を確認してください。

• プロバイダーの種類：Gemini または OpenAI-compatible。
• プロバイダーのホスト：https://www.pandai.vip のように、ホストのみを指定します。/v1 や /v1beta は含めないでください。
• API キー。ユーザーにはキーをクリップボードにコピーして「copied」と返信してもらう方法を優先してください。チャットに秘密情報を貼り付けるよう求めることは避けてください。

その後、非対話型コマンドを使用してください。

Gemini 互換のサードパーティチャンネル：

picgen provider quick-add gemini-proxy --host https://www.pandai.vip --prefer
picgen key set PICGEN_GEMINI_PROXY_KEY --clipboard
picgen provider test gemini_proxy --json

OpenAI 互換のサードパーティチャンネル：

picgen provider quick-add openai-proxy --host https://www.pandai.vip --prefer
picgen key set PICGEN_OPENAI_PROXY_KEY --clipboard
picgen provider test openai_proxy --json

クリップボードにアクセスできない場合は、picgen key set の標準入力から API キーを渡してください。ユーザーがそのリスクを明示的に受け入れない限り、シェルの履歴に秘密情報を直接残さないでください。エージェントのランタイムで標準入力を安全に渡せない場合は、ユーザーにターミナルで picgen key set <ENV_NAME> を実行し、非表示のプロンプトにキーを入力するよう依頼してください。

秘密情報の値を明かさずに設定済みのキーを確認するには、次を実行してください。

picgen key list --json
picgen key show PICGEN_GEMINI_PROXY_KEY --json

これらのコマンドで表示されるのは、情報源、長さ、マスクされたプレビュー、フィンガープリントのみです。確認だけを目的として、キーをチャットに貼り付けるようユーザーに求めないでください。

キーの確認についてユーザーに説明する場合は、次のように伝えてください。「この会話では、マスクされたキーのステータスのみを読み取り、秘密情報全体は読み取っていません。保存済みの完全なキーを自分で確認または編集する必要がある場合、PicGen が管理するキーファイルは ~/.picgen/.env です。現在のディレクトリにあるプロジェクトレベルの .env がこれを上書きすることがあり、シェル環境変数が最優先されます。」

参照画像を生成する場合は、ローカル画像を繰り返し指定する --reference <path> フラグで渡してください。

picgen create --dry-run --reference ./reference.png --preset poster "<prompt>"
picgen create --reference ./reference.png --preset poster "<prompt>"

ローカル画像の編集やインペインティングを行う場合は、少なくとも 1 枚の参照画像とともにマスク画像を渡してください。

picgen create --dry-run --reference ./source.png --mask ./mask.png --preset poster "<prompt>"
picgen create --reference ./source.png --mask ./mask.png --preset poster "<prompt>"

OpenAI-compatible プロバイダーでは、参照画像が指定されている場合は /v1/images/edits を使用し、image[] をマルチパート形式でアップロードします。マスクが指定されている場合は、mask をマルチパート形式でアップロードします。Gemini プロバイダーでは generateContent を使用します。マスクはネイティブのインペインティングではなく、明示的な編集指示と組み合わせたマスクガイダンス画像として扱われます。

PicGen はプロバイダーの機能に基づいてルーティングします。参照画像が指定されている場合、ユーザーが特定のプロバイダーを明示的に指定していない限り、エージェントは --provider を省略し、PicGen に reference-image をサポートするプロバイダーを選択させることができます。

最初のスモークテスト

プロバイダーの設定後、低コストで高速な 1 枚生成プランを使って最初のテスト生成を実行してください。最初の確認では、poster、product-shot、social-cover、プレミアムモード、大きなサイズ、高品質プリセットを使用しないでください。

Gemini プロバイダーの場合、最初のテストには flash 画像モデルを優先してください。

picgen create --dry-run --provider gemini_proxy --preset fast-draft --model gemini-3.1-flash-image-preview "一张简洁的 PicGen 测试图，白色背景，少量蓝绿色科技感点缀"
picgen create --yes --provider gemini_proxy --preset fast-draft --model gemini-3.1-flash-image-preview "一张简洁的 PicGen 测试图，白色背景，少量蓝绿色科技感点缀"

OpenAI-compatible プロバイダーの場合：

picgen create --dry-run --provider openai_proxy --preset fast-draft "一张简洁的 PicGen 测试图，白色背景，少量蓝绿色科技感点缀"
picgen create --yes --provider openai_proxy --preset fast-draft "一张简洁的 PicGen 测试图，白色背景，少量蓝绿色科技感点缀"

ユーザーがすぐに生成するよう明示的に依頼していない限り、ドライランのプレビューを提示し、実際に生成する前に確認を求めてください。最初のスモークテストでは画像を 1 枚生成してください。

プロバイダーの設定後

プロバイダーを 1 つ設定し、最初のスモークテストに成功したら、プロバイダーが使用可能になったことをユーザーに伝え、フォールバック用に別のチャンネルを追加するか確認してください。例：

Gemini 渠道已经配置并测试成功。你还可以继续添加另一个渠道作为备用，例如 OpenAI-compatible。要继续添加吗？

ユーザーが追加を希望する場合は、次のチャンネルのプロバイダー設定とスモークテストを繰り返してください。希望しない場合は、設定を終了し、PicGen を使用できる状態になったことを伝えてください。

環境設定と上書き

picgen create のフラグは、その実行に限った上書きとして扱ってください。ユーザーの環境設定を変更してはいけません。

picgen create --provider gemini_official "<prompt>"
picgen create --model gemini-3-pro-image-preview "<prompt>"
picgen create --preset poster "<prompt>"
picgen create --mode premium "<prompt>"
picgen create --reference ./reference.png "<prompt>"
picgen create --mask ./mask.png --reference ./source.png "<prompt>"

「今後はデフォルトで Gemini を使う」のように、ユーザーが設定を記憶するよう明示的に依頼した場合にのみ、デフォルトを変更してください。

出力の処理

PicGen はプロバイダーの応答をローカルの画像ファイルに正規化します。プロバイダーは URL、base64、インラインのバイトデータ、ファイル参照を返すことがありますが、エージェントが使用するのは PicGen のローカルパスとメタデータだけにしてください。

生成後：

• 画像のプレビューまたはローカルパスを表示します。
• base64、画像のバイナリデータ、プロバイダーの応答全体を会話に貼り付けないでください。
• 明示的にデバッグを求められない限り、メタデータからプロバイダーの応答ペイロードを読み取ったり表示したりしないでください。
• 生成した画像を自動的に読み込んだり、添付したり、分析したり、再送信したりしないでください。
• ユーザーが画像の確認、編集、続きの生成、比較を求めた場合にのみ、生成した画像を読み込んでください。
• 読み込みが必要な場合は、参照された特定の画像だけを読み込んでください。

ユーザーから尋ねられない限り、通常のユーザーにトークンやコンテキストの管理について説明しないでください。

PicGen は生成画像のペイロードと Gemini の思考シグネチャをメタデータから削除しますが、エージェントも引き続きメタデータをユーザー向けコンテンツではなく、診断情報として扱ってください。

エラー処理

doctor で使用可能なプロバイダーがないと報告された場合は、プロバイダーを設定してください。エージェント環境では、非対話型のセットアップを優先してください。

API キーが不足している場合は、picgen key set <ENV_NAME> --clipboard または --stdin で保存するか、対話型プロンプトが表示されている場合は、ユーザーに picgen setup を実行するよう案内してください。デバッグに役立つ場合にのみ、必要な環境変数の名前を伝えてください。

プロバイダーが無効になっている場合は、有効にするか、単発でプロバイダーを上書きして使用するよう提案してください。

参照画像なしでユーザーからマスクが提供された場合は、生成前に元画像または参照画像を要求するか、見つけてください。マスクは元画像と組み合わせて使用する必要があります。

プロバイダーの呼び出しに失敗した場合は、簡潔なエラーを表示し、可能であればメタデータまたはエラーのパスを案内してください。ユーザーがフォールバック動作を承認していない限り、別の有料プロバイダーで黙って再試行しないでください。

例

明示的な指定：

用 PicGen 生成一张产品发布海报

確認：

我可以先用 PicGen 做一次轻量测试生成，默认只出 1 张，确认工具和渠道都可用。要我现在开始吗？

生成プレビュー：

生成预览：
我将使用当前渠道生成 1 张轻量测试图，保存到本地。

确认后开始生成。