illo

Illo

文章コンテンツ向けに、独創的で個性のあるエディトリアルイラストを作成します。1枚の画像で1つのアイデアを説明します。重要な判断、流れ、ビフォーアフター、落とし穴、ループなどです。繰り返し登場するマスコットが、すべてのシーンでアイデアを実演します。マスコットは主役であり、飾りではありません。1つのアイデアが段階を経て進む場合は、1枚の画像に2〜4コマを収めたミニコミックにできます。また、アイデア自体がたどれる構造（パイプライン、ラベル付きステージ、ファンアウト、タイムライン、ループなど）の場合は、解説図にできます。同じマスコットとビジュアルで、手作りのスケッチ図として矢印や吹き出しを使い、構造を描きます（references/composition.mdの「2つの表現」と「図の種類を選ぶ」を参照。エディトリアルシーンが常にデフォルトです）。名前の付いたパイプラインやレシピは、この表現形式のラベル付きステージとして、名前の付いたフェーズを順につなげた1つのシステムにします。このボディ向けにパックのスタイルで解決され、新しいビジュアルにはなりません。または、キャラクター切り抜きとして、後から重ねて使うために、マスコットだけを透明なPNGにできます。ポーズと接地の連続性のみを描き、アイデア、テキスト、背景は含めません（references/cutout.md）。

これは設定可能なハウススタイルであり、汎用の画像生成ツールではありません。手法は一定で、キャラクターパックとパレットがパラメーターです。また、キャラクターパックにはスタイルも含まれます。1パックにつき1つのビジュアルを、同梱のスタイルライブラリ（riso — 粗いハーフトーン、インク層のずれ、紙の質感、太く柔らかな丸みのある輪郭線に加え、blueprint、woodcut、pixel、clay、manila、chalk、phosphor、enamel、gouache、felt、diorama、sketchbook、bricks、fizz、bloom、snes）またはカスタムスタイルファイルから選びます。デフォルトのマスコットは、risoスタイルの無表情なインクのしずく、Blotです。パレットには、プリセット、ユーザー独自のパレットファイル、または1色から導出した色を使います。パラメーターにかかわらず、意図的に写真風にはしません。ただし、玩具のブロックを撮影したようなスタイルのbricksは例外です。ロゴ風でも、企業向けインフォグラフィック風でも、形式ばった箱とひし形のフローチャート風でも、UIモックアップ風でもありません。フローチャートを依頼された場合も、パックのビジュアルで表現したラベル付きステージになります。形式ばった見た目の禁止はビジュアルの制約であり、「フローチャート」という言葉を拒否するものではありません。

ユースケース — リクエストの振り分け

ユーザーの要望	手順
記事／投稿／ニュースレター／URLをイラストにする	ステップ 0～7：まずソースを振り分けます（主旨 → カバー範囲：ヒーロー／ヒーロー＋セット／セット／ミニコミック — references/composition.md、「Source routing」）。次にショットリストを作成し（ヒーローの行＋アンカー）、各アンカーにつき画像を 1 枚作成して、配置に応じて挿入します。
1 つの概念を 1 枚の画像にする	ステップ 1 のコンセプト分岐（アイデアが漠然としていれば、簡単な質問を最大 3 つ）に進み、画像を 1 枚作成します。
おまかせ／ランダム — 「surprise me」、「random」、「surprise me with art quote using bray」、「surprise me --autopick」	references/surprise.md を最後まで読みます。まずステップ 0 を実行し、次にキャラクターと出典を決めます（defaultCharacter は無視します。「* quote」は出典付きの引用を強制し、それ以外は約 1/3 の確率で引用を選びます）。安全な候補を 3 つ作成し、対話型ピッカーまたは最適候補の自動選択（スケジューラーには --autopick を推奨）を行ってから、確定した言葉をもとに登録し、ステップ 3～7 を実行して画像を 1 枚作成します。言葉と画像を納品します。ポスターのタイトルはデフォルトで無効です。ミニコミックには引き続きパネルごとのラベルが付きます。
一連の流れ — ストーリーの展開、変更前→変更後、失敗→修正	展開が 1 か所で完結する場合は ミニコミック（references/composition.md の形状ルーティングを参照 — 形を決めるのはアイデアであり、出力先ではありません）。指定されたプロセス図／フローチャート／ラベル付きワークフローは、この行ではなくラベル付きステージです。
追跡可能な構造 — 「フローを見せて」、「ラベル付きのステージで」、「手順にラベルを付けて」、「各ステージを順に説明して」、「パイプラインを図にして」、「あの工場の図のように」、「手順をマッピングして」、「解説図として」、またはフローチャート／ラベル付きワークフロー／プロセス図を明示的に指定	解説レジスター（references/composition.md の「Pick the diagram type」と「The explainer register」）：現在のルックで、手作業でラベルを付けたステージ／フロー／分岐／タイムライン／ループ／スタック／システムの一部を作成し、マスコットもその一部として機能させます。フローチャート／ラベル付きワークフロー／プロセス図を明示的に指定した場合、パックのルックに合わせた ラベル付きステージ に固定します。正式なフローチャートを禁止するのはルックの制約です（Visio、タイトル／凡例／グリッドは使用しません）。「フローチャート」という言葉を拒むという意味ではありません。ラベル付きステージは解説の中の構造タイプであり、新しいレジスターやルックではありません。プロンプトを作成する前に、現在のキャラクターに合わせてパック内で解決します。単位の主旨が名前付きのパイプライン、レシピ、または段階的なプロセスである場合に最適です。すべての解説で自動的に選ぶものではありません。
X の投稿／記事本文向けのソーシャル対応アート	16:9（正方形が明確に適している場合は 1:1）、大胆な ink-punch。設定されているか、依頼された場合は、x ハンドルで透かしを入れます。
X Article のバナー／ヒーロー画像	ユーザーが X Article のヒーロー／バナーを求めている場合は、専用のバナー形式 1536 × 640 px を使用します。通常の illo.py generate 画像パイプラインでプロンプトを作成してレンダリングし、キャラクター／オブジェクトの比率を歪めず、トリミングに備えて十分な余白を確保します。ユーザーが後処理を明示的に求めていない限り、別の画像から手作業で合成したり、トリミングし直したりして対応してはいけません。
ブログ／ブランド／サイトに合わせたアート	名前付きまたはカスタムのパレットを使うか、1 つの優勢な色からパレットを導きます（references/palettes.md）。
独自のマスコット — 「キャラクターを作って」、「私たちのマスコットを使って」、「Blot を置き換えて」	キャラクタービルダーを使用します。references/character-builder.md を最後まで読み、最初から最後まで指示に従ってください。
コミュニティのキャラクター — 「利用できるキャラクターは？」、「blip をインストールして」、「すべてのキャラクターをインストールして」、「mole を更新して」、「私のキャラクターを公開して」	references/pack-sharing.md を参照します。エンジンの packs list/show/install/update（packs install --all を含む）を使って操作し、GitHub PR で公開します。
別のルック — 「blueprint で」、「木版画風で」、「blip のピクセル版」	スタイルはキャラクターパックに付属します。references/character-builder.md の「Style variants」を参照して、スタイルバリアントパックを作成します。
選択肢がほしい、または「どのモデルが最適？」	ステップ 5b：--count でバリエーションを生成するか、モデルループを実行し、推奨案とともに gallery を表示します。
既存の画像を修正する（不要なタイトル、色の変更、マスコットが装飾的すぎる）	references/prompt-recipe.md のプロンプトを編集し、画像を --ref として渡します。
キャラクターの切り抜き／透明 PNG／オーバーレイ用ステッカー — 「マスコットだけ」、「背景なし」、「ほかのものに貼り付ける」	切り抜きレジスター（references/cutout.md）を使用します。最後まで読み、references/prompt-recipe.md の「Cutout variant」をもとにプロンプトを作成し、--cutout と --aspect 1:1 を指定して生成します。OpenRouter の切り抜きでは、デフォルトで GPT Image 2 を使用します（Grok ではありません）。アイデアの説明には使用しません。場面が必要な依頼なら、編集用のルートに振り分け直します。
アニメーションするアイドル状態／ボットアバター／マスコットのループ GIF	切り抜きレジスターと、references/cutout.md の「Idle loop / bot avatar」を使用します。--cutout を指定し、キャラクターシートを --ref として、透明な 1:1 の切り抜きを 1 つ作成してから、その PNG にプログラムで動きを付けます。

前提条件

エンジン（scripts/illo.py、標準ライブラリの Python のみを使用し、インストール不要）は、3 つのエンジンバックエンドと2 つのエージェント側トランスポートを通じてレンダリングします。必須要件は python3 とネットワークアクセスのみです。Grok Bot（Cursor の Grok Bot／Grok デスクトップアシスタント）はエージェント側トランスポートです。ユーザー設定でエンジンバックエンドが明示的に選択されていない場合は、illo.py generate ではなく、組み込みの Grok 画像ツールを直接使用してください。もう一方のエージェント側トランスポートはMuse（Meta のパーソナルアシスタント、Blip）です。あなたが Blip である場合は、このスキルに従って illo プロンプトを作成し、アクティブなキャラクターシートを参照として添付して、ネイティブの画像生成ツールを呼び出してください。画像 API を提供しているだけの他のエージェントは、どちらのネイティブ経路も使用してはいけません。エージェント自身の組み込み画像ツールを呼び出せ、かつ上記に名前が記載されている必要があります。

エンジンの実行 — 各ブロック内で $SKILL_DIR を設定してください。 以下のすべてのエンジンコマンドは python3 "$SKILL_DIR/scripts/illo.py" … の形式です。SKILL_DIR には、この SKILL.md が読み込まれたディレクトリの絶対パス（scripts/illo.py と assets/ を含む）を設定し、それを使用する同じコマンドブロック内で設定してください。別々に実行したコマンド間ではシェルの状態が保持されないため、前のブロックで設定した値は次のブロックでは失われます。ハーネスからそのパスを取得できない場合は、インストール済みの scripts/illo.py を見つけて、その親ディレクトリを使用してください。どちらも特定できない場合は、作業ディレクトリを推測せずに中止してください。エンジンはバンドルされたアセットの場所を自動で特定するため、$SKILL_DIR は illo.py の起動と、バンドルされたキャラクターシートを --ref に指定できる程度に正しければ十分です。

ブロックはフラット化しても安全な形式で記述してください。一部のホスト（Codex で確認済み）では、コードフェンス内のブロックが 1 行にまとめられ、改行がスペースに置き換わることがあります。代入の末尾には ; を付けてください（SKILL_DIR="…";）。付けない場合、フラット化された SKILL_DIR="…" python3 "$SKILL_DIR/…" は環境変数プレフィックスとして扱われ、代入が適用される前に $SKILL_DIR が空に展開されるため、パスが /scripts/illo.py になってしまいます。代入行やコマンド行にはコメントを付けないでください（フラット化で # 以降の行がすべてコメントアウトされ、コマンドが何も出力せず消えてしまいます）。各呼び出しは1 行にまとめてください（フラット化された \ による継続は、余計な引数を挿入します）。値が間違っているか未設定の場合、doctor（ワークフローのステップ 0）はエラーを明示して失敗します（can't open file …/scripts/illo.py）。これはパスを修正すべき合図であり、スキルの不具合ではありません。

• Codex バックエンド（Codex サブスクライバーは無料）。 ホストで利用可能な Codex CLI（インストール済みで、codex login 済み、image_generation 機能が有効）があれば、illo はユーザーの Codex サブスクリプションを通じて 画像ごとの料金なしで生成できます（ユーザーの Codex クォータを使用します）。 API キーもトークンも不要です。illo はユーザー自身の CLI を呼び出すだけです。 自動検出されるため、前提とはしません。gpt-image-2 が自動的に選択されます。 Windows/WSL ではサポートされていません。
• Grok CLI バックエンド（Grok/xAI サブスクライバーは無料）。 ホストで利用可能な Grok CLI（インストール済みで、grok login 済み）があれば、illo は grok -p（ヘッドレス）を介してユーザーの Grok サブスクリプションで生成でき、 Grok のクォータを使用します。Codex と同じく、環境変数もトークンも不要な サブプロセス設計です。Grok はアルファチャンネルのない JPEG を返すため、 透明な切り抜きは作成できません。その場合は、切り抜きに対応したバックエンドに 自動的にフォールバックします。画像ツールにモデル選択機能はありません。
• Grok Bot ネイティブトランスポート（エージェント側、Grok Bot ユーザーは無料）。 あなたが Grok Bot（具体的には Cursor の Grok Bot、または Grok の組み込み画像 ツールを備えたデスクトップアシスタント）である場合は、illo プロンプトを作成し、 アクティブなキャラクターのモデルシートを参照画像として、そのツールを呼び出して ください。Grok CLI、Codex CLI、OpenRouter キーを要求してはいけません。 エンジンバックエンドがないことを init を実行する理由にしてはいけません。 これは汎用的な「ホスト画像 API」のルールではなく、illo.py --backend の値でも ありません。
• OpenRouter バックエンド（有料、直接利用または明示的なフォールバック）。 ユーザーの設定ファイルに OpenRouter API キー（唯一の認証情報の受け渡し方法） が必要です。ユーザー自身が実行する init によって一度だけ書き込まれます （モード 600）。エンジンは環境変数からシークレットを読み取らず、コマンドライン 引数として受け付けることもありません。サブスクリプション CLI がないホストでも、 このエンジンパスを直接選択できます。Codex/Grok CLI によるレンダリングが失敗しても、 自動的に料金が発生することはありません。有料フォールバックには --allow-paid-fallback が必要です。モデルを選択できます （--model）。

バックエンド／トランスポートの仕組み（解決と優先順位、CLI の要件、Grok Bot の ネイティブパス、組み込み画像ツールの自動選択、クォータと料金、切り抜きの制限、 Windows/WSL、フォールバック）をまとめた資料です。バックエンドを選択または説明する 前に、references/backends.md を最初から最後まで読んでください。 仕組みはそこに一度だけ記載されています。

セットアップはユーザーが行います（キーを自分で入力しないでください）

API キーを入力するのはユーザーです。ユーザーのキーを入力、貼り付け、表示、 保存してはいけません。ユーザーに次の方法で初期設定するよう案内してください。

• 初期設定（ユーザーが実行）： python3 "$SKILL_DIR/scripts/illo.py" init — 非表示のプロンプトでキーの入力を求め（入力内容は表示されません）、YAML 設定 ${XDG_CONFIG_HOME:-~/.config}/illo/config.yaml を書き込みます（モード 600）。 シークレットではないデフォルト値（--model、--palette、--aspect、 --character、--watermark）も保存できます。保存済みのキーに触れずに設定を 更新するには、--no-key を使用します。（PyYAML がインストールされている場合、 設定の読み取りに PyYAML が使用されます。インストールされていない場合でも、 最小限の組み込みパーサーが apiKey、model などのフラットなキーを読み取るため、 生成に追加のインストールは不要です。watermark などのネストされた設定に限り PyYAML が必要です。python -m pip install 'PyYAML==6.0.2'）
• シークレットではない設定は、同じコマンドと --no-key を使ってユーザー向けに 初期設定できます。ただし、キーを入力するのはユーザー自身です。

Hermes Agent のみ：バイナリアセット修復の事前チェック

Hermes の一部のバージョンでは、GitHub から複数ファイルのスキルをインストールする際にバイナリファイル（同梱のキャラクターシート）が破損することがあります。テキストファイルはそのまま残りますが、バイナリファイルは破損し、シートが破損するとキャラクターロックが気付かれないまま機能しなくなります。Hermes Agent では、初回使用前、および doctor が assets: CORRUPTED と報告した場合に、次の処理を一度実行してください。

bash ${HERMES_SKILL_DIR}/scripts/repair-hermes-assets.sh

同梱されているすべてのバイナリを既知の正常な SHA256 ハッシュ（assets/checksums.txt）と照合し、不一致のファイルのみを、固定された変更不可の URL から再ダウンロードします。すべて正常であれば何も実行しません。Claude Code、Codex、OpenClaw、またはファイルを正確にインストールするその他のランタイムでは、この処理を省略してください。doctor はあらゆる環境でアセットの整合性を確認し、修復が必要な場合に通知します。

必要に応じてこれらのリファレンスを読む

一度にすべて読み込まないでください。各ステップに合ったファイルを取得してください。

• references/visual-style.md — riso。標準のルックであるリソグラフ技法、線の表現、紙とインク、厳守すべきルールを説明します。
• references/styles/<name>.md — そのほかのルックライブラリ（blueprint、woodcut、pixel、clay、manila、chalk、phosphor、enamel、gouache、felt、diorama、sketchbook、bricks、fizz、bloom、snes）。キャラクターパックで使用します。生成前に、使用するキャラクターのスタイルファイルを最後まで読んでください。
• references/character.md — キャラクターのルール（設計を支えるテスト、複雑さを抑えるガードレール、値はパレットに従うという原則、インタラクションモデル — パックごとに定義するか、確定したデザインとリファレンスシートから慎重に導出します）、デフォルトキャラクターの Blot、カスタムパックの形式を説明します。キャラクターに関する作業の前に読んでください。
• references/character-builder.md — ユーザー独自のマスコットを設計してインストールするためのガイド付き手順を説明します。キャラクターの作成または置き換えの前に、最後まで読んでください。
• references/pack-sharing.md — コミュニティリポジトリからのキャラクターのインストールと、PR によるパックの公開方法を説明します。インストールまたは公開の依頼を受けたら、作業前に読んでください。
• references/palettes.md — 名前付きプリセット、デフォルトの解決方法、カスタムパレット、1 色からパレットを導出するアルゴリズムを説明します。パレットの選択または導出の前に、最後まで読んでください。
• references/composition.md — 2 つのレジスター（エディトリアルシーン／解説図）、図の種類の選択、解説図の構成タイプと予算（ラベル付きの段階、矢印の注記、パックの解法を含む）、配置、アイデアを動きに変える方法、身体部位と動作の実現可能性ゲート（描画前に接触マップをキャラクターのインタラクションモデルと照合して検証します）、構図の再利用禁止ルール、ショットリストの形式を説明します。
• references/cutout.md — 切り抜きレジスター（透明な合成素材、接触の連続性、ポーズの語彙、生成フラグ）を説明します。切り抜きの依頼を受けたら、作業前に最後まで読んでください。
• references/surprise.md — サプライズ／ランダムモード（事前確認を優先、対象範囲の解析、ランダムなキャラクター、出典の多様性とセリフ候補 3 つ（出典のあるモードでは並列検証も任意）、対話式ピッカーまたは --autopick／自動で最適候補を選択、更新時の全面的な再抽選、セリフ確定後のレジスター、セリフバーと意味バー、複数ソースによる引用の検証、提案前の安全性確認、ヘッドレス時の仕様）を説明します。サプライズ／ランダムの依頼を受けたら、作業前に最後まで読んでください。
• references/backends.md — 3 つのバックエンドを持つ画像エンジンと Grok Bot のネイティブトランスポート（エンジンのバックエンドの解決順序（Codex > Grok > OpenRouter）、自己識別ルール、Grok Bot が illo.py generate を経由しない条件、Codex／Grok CLI の要件、成果物を優先する成功判定、組み込みの画像ツールは自動で使用されモデル選択は不要であること、クォータと課金の違い、Grok の切り抜き制限、Windows／WSL、有料フォールバックのオプトイン）を説明します。バックエンドの選択または説明の前に読んでください。
• references/models.md — モデルの一覧（OpenRouter バックエンドのみ）：わかりやすい名前と OpenRouter ID の対応表、特性、アスペクト比に関する注意点、404／フォールバックの処理を説明します。--model を渡す前に読んでください。
• references/prompt-recipe.md — 生成プロンプトのテンプレートと、編集／再着色のプロンプトを説明します。
• references/quality-bar.md — 生成後のチェックリストと反復ルールを説明します。成果物を提示する前に読んでください。

assets/character-reference.webp はデフォルトキャラクターの正式なモデルシートであり、一貫性を保つための基準（下記のエンジンが使用）です。カスタムパックには独自のモデルシートが付属します。スタイルの調整例は 同梱されていません。各スタイルファイルに記載された URL から必要に応じて取得し、線の密度、余白、アクセントの抑制を確認してください。構図をそのままコピーしてはいけません。現在の作品に合った新しい比喩を考案してください。

ワークフロー

0. 事前確認

生成する前に、エンジンが使用可能な状態であることを確認します。

SKILL_DIR="<path to this skill>";
python3 "$SKILL_DIR/scripts/illo.py" doctor

illo.py の呼び出しは単独で実行してください。&& で連結しないでください。表示される終了コードそのものが準備状態のシグナルです（0 = 準備完了）。連結したコマンドの隣の処理が失敗すると、正常なチェックがエラーとして表示されます。

python、設定ファイルのパス、解決されたモデル／パレットのデフォルト、カスタムキャラクターパックまたはカスタムパレットファイルの有無、Codex/Grok CLI の検出状況と解決されたバックエンド／トランスポート、および OpenRouter キーが見つかったかどうか（キー自体は表示しません）を報告します。終了コード 0 = 解決されたバックエンドの準備完了です。OpenRouter のみをインストールしている場合（サブスクリプション CLI なし）も終了コード 0 のままです。準備状態は固定のキー確認ではなく、解決されたバックエンドに基づきます（references/backends.md）。

Grok Bot ネイティブパス（エージェント側）。 あなたが Grok Bot（Cursor の Grok Bot／組み込みの Grok 画像ツールを備えた Grok デスクトップアシスタント）で、ユーザーが backend: openrouter、backend: codex、backend: grok を明示的に選択していない場合は、doctor を頼りにする前にエージェント側トランスポートを初期化してください。

SKILL_DIR="<path to this skill>";
python3 "$SKILL_DIR/scripts/illo.py" init --backend grok-bot --no-key

その後、通常どおり doctor を実行してください。このパスでは終了コード 0 が有効な準備完了を示します。backend: grok-bot の場合、Codex CLI、Grok CLI、OpenRouter キーがなくても失敗ではありません。アセットの破損、カスタムパックの読み取り不可、パレットの形式不正、または SKILL_DIR の誤りは引き続き失敗となるため、レンダリング前に修正する必要があります。ステップ 5 では、アクティブなモデルシートを参照しながら、Grok Bot に組み込まれた Grok 画像ツールを呼び出して生成します。この方法は Grok Bot 自身の Grok 画像ツール専用です。無関係な画像ツールを使う他のエージェントは、以下のエンジンバックエンドを使用してください。

Grok Bot の簡易手順：バックエンドが未設定／自動の場合は、init --backend grok-bot --no-key を一度実行します。アセット／設定／パックの確認には doctor を実行し、通常どおり packs コマンドを使います（コミュニティキャラクターをローカルに配置するため、インストール後に packs install --all も実行してください）。同じリファレンスを読み、同じプロンプトを作成してから、アクティブなキャラクターのリファレンスを使って Grok Bot に組み込まれた Grok 画像ツールを呼び出します。ユーザーが明示的に OpenRouter または別のエンジンバックエンドをデフォルトにするよう希望していない限り、OpenRouter 用の illo.py init は省略してください。また、ユーザーがエンジンバックエンドを明示的に選択していない限り、illo.py generate も省略してください。

Muse ネイティブパス（エージェント側）。 あなたが Blip（Meta のパーソナルアシスタントである Muse）で、ユーザーがエンジンバックエンド（backend: openrouter、backend: codex、backend: grok）を明示的に選択していない場合は、doctor を頼りにする前にエージェント側トランスポートを初期化してください。

SKILL_DIR="<path to this skill>";
python3 "$SKILL_DIR/scripts/illo.py" init --backend muse-native --no-key

その後、通常どおり doctor を実行してください。このパスでは終了コード 0 が有効な準備完了を示します。backend: muse-native の場合、Codex CLI、Grok CLI、OpenRouter キーがなくても失敗ではありません。アセットの破損、カスタムパックの読み取り不可、パレットの形式不正、または SKILL_DIR の誤りは引き続き失敗となるため、レンダリング前に修正する必要があります。ステップ 5 では、アクティブなモデルシートを参照しながら、ネイティブ画像生成ツールを呼び出して生成します。Grok Bot とは異なり、このパスでは切り抜きが可能です。パックのクロマスクリーン上でレンダリングし、illo.py keyout を実行してください（references/cutout.md を参照）。この方法は Blip 自身のネイティブ画像ツール専用です。無関係な画像ツールを使う他のエージェントは、エンジンバックエンドを使用してください。

Muse の簡易手順：バックエンドが未設定／自動の場合は、init --backend muse-native --no-key を一度実行します。アセット／設定／パックの確認には doctor を実行し、通常どおり packs コマンドを使います。同じリファレンスを読み、同じプロンプトを作成してから、アクティブなキャラクターのリファレンスを使ってネイティブ画像ツールを呼び出します。ユーザーがエンジンバックエンドを明示的に選択していない限り、illo.py generate は省略してください。ネイティブレンダリングの場合は、illo.py record（切り抜きの場合は keyout）で記録し、実行の manifest.jsonl とギャラリーに追加してください。 設定の移行 — バックエンドの選択肢を対話形式で提示します。 illo.py generate を使用しようとして、doctor が backend: NEEDS CHOICE を報告する場合（または generate が「設定が古い」と表示して処理を停止する場合）、このユーザーの設定はバックエンドの選択肢が追加される前のものです。つまり、以前からインストールしているものの、サブスクリプション CLI を提示されたことがありません。ユーザーに代わって選択を黙って行わないでください。 プラットフォームのブロッキング質問機能（Claude Code では AskUserQuestion、その他では同等の機能を使用します。ホストにその機能がない場合（例：通常のチャットセッション）は、同じ選択肢を簡潔なメッセージで尋ね、返信を待ちます。決して黙って選択しないでください）を使って、次の対話形式の選択肢を提示します。「illo に画像バックエンド／トランスポートが追加されました。どれを使いますか？」選択肢は 5 つです。Codex（無料、Codex サブスクリプションを使用）、Grok CLI（無料、Grok サブスクリプションを使用。背景透過画像は作成できません）、Grok Bot（エージェント側のネイティブツール。Grok Bot の場合にのみ使用）、Muse（エージェント側のネイティブツール。Blip（Meta のパーソナルアシスタント）の場合にのみ使用）、OpenRouter（モデルを選択：Grok Imagine、Nano Banana、GPT Image など）。既存のキーには触れず、回答を保存します。 python3 "$SKILL_DIR/scripts/illo.py" init --backend <codex|grok|grok-bot|muse-native|openrouter> --no-key その後、処理を続けてください。新規インストール（設定がまったくない場合）は通常のオンボーディングであり、この移行は発生しません。

サブスクリプション CLI エージェントの場合は、自分の CLI を優先してください。 エンジンの自動デフォルト設定では、ホストの機能（Codex > Grok > OpenRouter）が参照されます（どのエージェントが呼び出したかは判別できません）。しかし、自分がどのエージェントかは分かっています。そのため、サブスクリプション CLI エージェントであり、このホストで自分の CLI を使用できる場合は、背景透過以外のレンダリングでは generate に自分のバックエンドフラグを追加してください。Grok CLI エージェントは --backend grok、Codex エージェントは --backend codex を追加します。これにより、Codex も利用できるホストであっても「Grok CLI では Grok で生成する」という動作を保てます。エンジンで実行時の検出を行う必要はありません。背景透過画像の作成ではこの設定は無視されます（Grok は作成できないため、自動的に代替手段に切り替わります）。ユーザーの設定にある backend: は、ほかのすべての設定より優先されます。解決方法と優先順位の仕組みについては references/backends.md を参照してください。

Grok Bot の場合、同等の自己識別ルールは generate の実行前に適用されます。バックエンドが未設定または自動の場合は、init --backend grok-bot --no-key で backend: grok-bot を保存し、上記のネイティブ Grok 画像ツールの経路を使用します。ユーザーがエンジンのバックエンドを明示的に設定または指定している場合は、Grok Bot のネイティブ機能に黙って切り替えず、その選択に従ってください。

Blip（Muse）にも同等のルールが適用されます。バックエンドが未設定または自動の場合は、init --backend muse-native --no-key で backend: muse-native を保存し、ネイティブ画像ツールの経路を使用します。ユーザーがエンジンのバックエンドを明示的に設定または指定している場合は、Muse のネイティブ機能に黙って切り替えず、その選択に従ってください。 キーが見つからないと判断する前に、表示された設定パスを確認してください。Hermes では、複数プロファイルの設定時にHOME／XDG_CONFIG_HOMEが別のプロファイルのホームを指すことがあります（例：…/profiles/<name>/home/.config/illo/…）。そのため、存在するキーが見つからないように見えることがあります。パスが誤ったプロファイルを指している場合は、キーが見つからないと判断せず、正しいHERMES_HOME／HOME／XDG_CONFIG_HOMEを指定して再実行してください。キーが本当に 存在しない場合は、ここで中止し、ユーザー自身に python3 "$SKILL_DIR/scripts/illo.py" initを実行するよう依頼してください。キーを代わりに入力してはいけません。チャットセッションではユーザーはその場でコマンドを実行できないため、まずユーザー側の作業を最小限に抑えます。自分でinit --no-keyを実行してください（許可されています。デフォルト値とコメント付きの# apiKey:プレースホルダーを含む設定を作成し、モード600で保存します。キーには決して触れません）。その後、ユーザーにエージェントを実行するマシン上で、一度だけ行う同等の方法を2つ提示してください（そのホストはユーザーのものです。エージェントをインストールした場所です）。python3 <resolved absolute $SKILL_DIR>/scripts/illo.py initを実行する（非表示のプロンプト）、または~/.config/illo/config.yamlを開いてapiKey:行に入力する方法です。キーをチャット経由で送信してはいけません。メッセージでキーを尋ねてはいけません。また、ユーザーが誤って貼り付けた場合も使用せず、openrouter.aiでそのキーを失効させ、ホスト上で新しいキーを設定するよう伝えてください（貼り付けられたキーはチャット履歴とプラットフォームのサーバーに残っています）。環境変数やその他の保存場所からキーを自分で設定ファイルにコピーしてはいけません。その行を書き込めるのはユーザーだけです。ただし、範囲を限定した例外が1つあります。ユーザーがプラットフォームのシークレット機能を通じてOPENROUTER_API_KEYを設定した、一時的なクラウドワークスペース（Claude Code web、Codex cloud、CI）です。この設定自体が、ユーザーによる意図的なワークスペース限定の同意であり、initに対話型プロンプトを表示したり永続的なホームに保存したりする場所がないため、その場合に限り、ワークスペースのシークレットから設定を一度だけ作成してください（README.mdの「Cloud & CI」にある1行のコマンドを使用します）。個人のマシンでは、環境変数が設定されていてもユーザーの意図は確認できません（他のツール用の可能性があります）。ルールは変わりません。決してコピーしないでください。

パックの最新状態確認の任意提案（事前確認、同意優先）。 この実行でインストール済みコミュニティパックを使って描画する場合（doctorでパックを確認でき、インストール時に.versionスタンプが付与されます）、任意で最新状態を確認してください。 python3 "$SKILL_DIR/scripts/illo.py" packs listを実行すると、古いインストールに[installed 1.0.0 — 1.0.2 available]のような表示が付きます。ここで確認を実行してもかまいませんが、提案するのは使用するパックが確定してからです。つまり、Step 2でキャラクターが確定した後（またはサプライズモードでキャラクターを選んだ後）、そのパックを使う最初の描画の直前です。確定したパックが古い場合は、上記の設定移行と同様、プラットフォームの応答が必須の質問機能を使って、一度だけ描画前に更新するか尋ねてください。明示的に「はい」と回答された場合に限り、packs update <name>を実行してください（更新するとローカルコピーが上書きされます。手動編集に関する警告と--asの代替方法についてはreferences/pack-sharing.mdを参照してください）。黙って更新してはいけません。また、ここで処理を止めてはいけません。「いいえ」という回答、オフラインのホスト、レジストリエラー、ヘッドレス／スケジューラーでの実行（例：サプライズモードの--autopick）の場合は、固定されたコピーを使って続行してください。宣言された## Interaction modelがないパックでも、保守的な導出方法（references/character.md）によって安全に計画できます。コミュニティからインストールしたパックを使わない場合は、確認を完全に省略してください。

1. 入力を読み取り、曖昧なコンセプトを手短に明確化します

入力は3種類あり、それぞれ異なる方法で扱います。

• サプライズ／ランダム（「surprise me」「random」「surprise me with art quote using bray」「surprise me --autopick」および類似の表現）— 依頼は、提示された主張を描くことではなく、考案して描画することです。いったん止まり、 references/surprise.md を最初から最後まで読み、まずステップ0を実行してから、そこでキャラクターと出典を確定します（defaultCharacter は無視し、キャラクターの指定がなければランダムに選びます）。セリフ候補を3つ作り、ピッカーまたは自動ベスト選択で1つに決めて固定し、確定したセリフに合わせて文体を選んでから、ステップ3～7を1枚の画像として続けます。この描画では、事前確認とパックの準備がすでに済んでいるため、ステップ0と2は省略します。以下の曖昧なコンセプト向けの質疑応答には進まないでください。具体的なアイデアをすでに示すプロンプト（「you are the bottleneck」をイラストにして、など）は、「surprise me」と書かれていてもサプライズモードではありません。

• URL／記事／貼り付け文／長文投稿には、それ自体に文脈があります。ただし、最初に目を引いた細部から生成してはいけません。まず振り分けます（references/composition.md の「Source routing」）。ソースの構成とジャンルを分類し、依頼された成果物の役割（この画像が対象読者に対して果たすべきこと）を推測し、その役割と、ソース中で最も描きやすい仕組みを切り分け、主題を1文で確定します（ヒーロー画像で確定するのは、ソース／成果物の役割であり、最も目立つ根拠ではありません。ジャンルごとのガードレールに、各ジャンルで何を主役にするかが示されています）。その後、まずカバレッジの形式を選びます。ヒーロー、ヒーロー＋セクションごとのセット（記事全体の役割を担うもの）、セット、ミニコミック、またはショットリストから選びます。セットには配置先が必要です。短いソース（ツイートや1つのコンセプトなど）からセットを作ることはありません。複数の展開がある形式はミニコミックです。判断、ループ、入力→出力、前後関係、または落とし穴が現れる重要な場面を拾います。段落ごとに1枚の画像を作ってはいけません。何についての文章かはすでに示されているため、ユーザーに問いただしてはいけません。ただし、例外が1つあります。 複数の展開を含む実質的なソース（長い記事、事後検証、複数の主張を含むローンチ）では、ユーザーがすでにカバレッジを指定していない限り、複数画像の作成に取りかかる前にカバレッジについて1つだけ質問します。複数の展開を含むソースから画像を1枚だけ作る場合はヒーロー画像とし、その旨を伝えます。記事全体をカバーするものとしてはいけません。

• 単独のコンセプトや一文だけの依頼（例：「you are the bottleneck」をイラストにして）は、通常、画像を作るための情報が不足しています。出力を変える質問だけを、最大3つほど簡潔に尋ねてから作成します。 次の項目を参考にしてください。

  • 伝えたいこと（読者にどんな結論を持ち帰ってほしいか）。
  • 掲載先（ブログ／スライド資料／X の投稿／X の記事本文／X Article のバナー → 配色、アスペクト比、ピクセルの正規化、透かしが決まります）。
  • 形式：1枚の画像（デフォルト）、ミニコミック（1枚の画像に2～4コマ。アイデア自体が段階的に展開する場合のみ）、または複数の個別画像。さらに、必ず含める要素や制約も確認します。形式はアイデアに合わせて決め、掲載先に合わせてはいけません（references/composition.md）。

  短いやり取り1回までにして、その後は作成に進みます。ユーザーがすでに十分な情報を示している場合、「そのまま作って」／「1枚だけ」と言っている場合、または文脈から答えが明らかな場合は、質問をすべて省略します。明確な依頼に質問して作成を妨げてはいけません。

2. キャラクターを解決する

サプライズ／ランダムモード： この手順はスキップします。キャラクターは references/surprise.mdですでに解決されています（名前付きパック、またはインストール済みパック＋Blotからのランダム選択。defaultCharacterは対象外です）。ステップ3以降に進んでください。

インストール済みパックは${XDG_CONFIG_HOME:-~/.config}/illo/characters/にあります （形式と場所の詳細はreferences/character.md）。doctorで インストール済みのパックを一覧表示できます。ユーザーは複数のパックを保持し、実行ごとに選べます。最初に一致したものを使います。

1. 明示的なリクエスト — 「<パック名>を使って」「<名前>として」：そのパックを使います（名前で指定された場合は、同梱のデフォルトであるblotも含みます）。その単語がパック名に一致しない場合は、近似検索で解決します。インストール済みパックのAliases:行と題材（character.mdの冒頭行およびLocked designのBody）に照らし合わせ、さらにカタログのdescription（packs list）とも照合します。よくあるケースではdoctorが名前とエイリアスを出力するため、ファイルを読む必要はありません。たとえば「oxを使って」は、oxを題材にした副題のパック（例：yoke）を見つけます。明確な一致が1つならそれを使い、名前を伝えます。複数あればどれを使うか尋ねます。一致がなければ、そのことを伝えてから次に進みます。
2. 設定のデフォルト — 設定されている場合は、ユーザー設定のdefaultCharacterを使います。
3. 同梱のデフォルト — Blot（仕様はreferences/character.md、モデルシートはassets/character-reference.webp）。

解決したら、そのパックのcharacter.mdを読み、デフォルトのものを使う箇所すべてで、記載されたプロンプト仕様、値のルール、任意の**Cutout chroma:**互換性設定、およびreference.pngを使用します。

記事セットを新しいキャラクターに切り替える場合、特に試行がうまくいかなかった後や、技術／プラットフォームに関するエッセイの場合は、計画またはレンダリングの前に references/article-set-character-reroute.mdを最後まで読んでください。レンダリングにコストをかける前に、そこに記載された可読性の事前確認を行ってください。

ユーザーが新しいキャラクターを望む場合は、キャラクタービルダーを使います （references/character-builder.md）。他の人が作ったものを望む場合は、コミュニティリポジトリからパックをインストールします（references/pack-sharing.md）。いずれの場合も、まずインストールしてから、ここに戻って続けてください。

3. 計画（ショットリスト） — 計画を求められた場合、または複数画像を作成する場合

ユーザーが計画（「どこにイラストを入れるべきか」「ショットリスト」など）を求めた場合は、生成前にショットリストを出力します。画像ごとに、配置、1つのアイデア、アーティファクトの役割、表現のトーン（行が説明図の条件を満たす場合を除き、編集記事調）、構成（または構造の種類。references/composition.mdの「図の種類を選ぶ」を参照）、マスコットが何をしているか、配色、テキストの階層を記載します。アーティファクトに必要な場合は、主な読み取り要素／タイトルに加え、references/composition.mdにある表現のトーンごとの予算内で、短い補助ラベル／コールアウトも記載してください。アンカーの数に応じて画像の枚数を決めます（references/composition.mdにあるバンドと、決して水増ししないルールに従います）。文章の一部が同じ場所で段階を追って展開される場合は、複数の画像ではなく、そこで1枚のミニコミック画像を計画します。ミニコミックと個別画像のどちらを選ぶかは、references/composition.mdを参照してください。

記事セットのキャラクターを切り替える場合は、レンダリング前に references/article-set-character-reroute.mdにある必須の事前確認項目を追加します。項目には、セクションの主張、視覚的なオブジェクト／動作、読者との対応づけが含まれます。独自の比喩用語集が必要な行や、概念の置き換えが2つを超える行は却下してください。

4. パレットを解決する（キャラクターを形作るのはスタイルです）

スタイルは個別に解決できません。アクティブなキャラクターのパックに含まれており、そのキャラクターの character.md にある Style: 行で、同梱されたルック（references/styles/<name>.md、visual-style.md の riso）か、${XDG_CONFIG_HOME:-~/.config}/illo/styles/<name>.md にあるカスタムルックを指定します。行がない場合は riso です。Blot は riso です。riso 以外のスタイルでは、スタイルファイルをすべて読み込んでください。そこには STYLE と LINE LANGUAGE のプロンプトブロック、パレットのマッピング、キャラクターの描き方、追加の QA チェックが記載されています。同じキャラクターを別のルックで描くリクエストは、バリアントパックのビルド（ルートテーブル）です。その場でスタイルを変更してはいけません。

パレット：references/palettes.md をすべて読み込み、そこに従って解決してください。このファイルには、解決順序（明示的なリクエスト、ユーザーのパレットファイルによる出力先の手がかり、設定のデフォルト、ハウスパレットの ink-punch の順）、名前付きプリセット、カスタムパレット、1 色からパレットを導出するアルゴリズムが記載されています。最後は具体的な HEX 値にしてください。パックのスタイルが riso 以外の場合は、それらの値をスタイルのパレットマッピングに通してください。

5. 生成 — 参照画像に忠実に、画像ごとにメタファーは 1 つ

切り抜き分岐。 リクエストが切り抜きレジスターに振り分けられた場合は、まず references/cutout.md をすべて読んでください。ここには、バックエンドを考慮した透明化（デフォルトでは Codex のネイティブアルファ、OpenRouter または明示的な --chroma ではクロマキー互換モード）、位置合わせを固定したシルエット（インクレイヤーをずらさない）、--cutout ／ --aspect 1:1、OpenRouter の --image-config、マニフェストでの cutout_alpha の明記について記載されています。エディトリアル用テンプレートではなく、references/prompt-recipe.md の「Cutout variant」からプロンプトを作成し、手動の BACKGROUND: ／出力形式の指示は省いてください。エンジンが実際に実行するバックエンド用の要件は、エンジンが追加します。互換モードで再生成する場合に限り、--chroma を渡してください。--ref にはキャラクターのモデルシートのみを指定してください（エディトリアル用のスタイルアンカーやウォーターマークは指定しません）。QA は references/quality-bar.md の切り抜きセクションに照らして行ってください。エディトリアルのショットリストやテーマの手順は省略します。

エディトリアルおよび解説。 固定されたタイプがステージ表示の場合は、プロンプトを書く前に references/composition.md のパック解決用スクラッチ（「Labeled stages — skeleton, then pack-solve」）を実行してください（ステージリスト → オペレーターステージ → コンタクトマップ → バインド）。ルックを独自に考案してはいけません。画像ごとに、references/prompt-recipe.md に従って完全なプロンプト（シーン + 構成 + 伝達の優先順位 + スタイル + アクティブなキャラクターの仕様 + 解決済みパレットの HEX 値 + レジスターごとのテキスト上限）を作成し、ファイルに書き込んでからレンダリングしてください。アクティブなキャラクターのモデルシートを毎回 --ref として渡してください。この参照コンディショニングによってマスコットのモデルが保たれます。スタイルとパレットはプロンプトから指定するため、どちらも差し替え可能です。パックのシートはそのパック独自のスタイルで作られているため、シートとスタイルは常に一致します。異なるスタイルの参照を混在させてはいけません。（Hermes Agent の場合、最初の --ref 使用前に上記のアセット修復の事前チェックを実行しておく必要があります。シートが破損していると、すべてのレンダリングが不正な参照に基づいて生成されます。）

Grok Bot のネイティブレンダリング。 Grok Bot を使用していて、Step 0 からネイティブ経路が適用される場合は、illo.py generate を実行しないでください。同じ完全なプロンプトレシピ、同じアスペクト比、同じキャラクターの固定、セット内での同じスタイルアンカー規則を使用し、Grok Bot 組み込みの Grok 画像ツールを呼び出してください。アクティブなキャラクターのモデルシートを参照画像として添付してください（Blot の場合は assets/character-reference.webp、それ以外はパックの reference.png）。セット内の後続画像では、承認済みのスタイルアンカー画像も添付してください。生成したファイルを保存または返すようにツールに指示し、QA と納品では、その保存先パスをエンジン JSON の .path 相当として扱ってください。Grok Bot の画像ツールは、Grok CLI トランスポートと同じ Grok 画像モデルのクラスです。モデルセレクターはなく、OpenRouter での課金もなく、アルファチャンネルもありません。透明な切り抜きにはこの経路を使用せず、切り抜き対応のエンジンバックエンドに振り分けるか、そのバックエンドの設定を依頼して中断してください。 Muse ネイティブレンダリング。 あなたが Blip（Meta のパーソナルアシスタント、Muse）で、 Step 0 のネイティブ経路が適用される場合は、illo.py generate を実行しないでください。 同じ完全なプロンプトのレシピ、同じアスペクト比、同じキャラクターロック、セットでの同じ スタイルアンカーのルールを使い、ネイティブの画像生成ツールを呼び出してください。 アクティブなキャラクターのモデルシートを参照画像として添付します （Blot なら assets/character-reference.webp、またはパックの reference.png）。 セットの後続画像には、承認済みのスタイルアンカー画像も添付してください。ネイティブの画像呼び出しは、 1 つの応答につき最大 4 件までまとめて実行できます。それを超える場合は、フォローアップで続けてください。 返された各ファイルを実行ディレクトリに保存し、illo.py record（使い方を参照）で記録します。 これにより、ラベルとプロンプトを含む muse-native マニフェスト行が追加され、 エンジンレンダリングと同様にギャラリーに表示されます。QA と納品では、記録されたパスを エンジン JSON の .path 相当として扱ってください。

Grok Bot とは異なり、この経路では切り抜きが可能です。ネイティブツールにパックの 単色クロマキー用スクリーン（パックでは green または magenta を指定）を使うよう指示し、 続いて illo.py keyout <screen.png> --chroma <green|magenta> --out <final.png> を実行して 透過 PNG を生成してください。クロマキーの選択、QA、不透明画像にフォールバックするルールについては references/cutout.md を参照してください。この経路にはモデルセレクターも OpenRouter の課金もありません。--model は適用されません。

SKILL_DIR はインラインで設定し（Prerequisites を参照）、同梱のシートを REF として使います。 カスタムキャラクターの場合は、アクティブなパックの reference.png を使ってください。この画像に限り、 設定またはデフォルトのモデルを上書きするには --model <id> を追加します（OpenRouter バックエンドのみ）：

SKILL_DIR="<path to this skill>";
REF="$SKILL_DIR/assets/character-reference.webp";
python3 "$SKILL_DIR/scripts/illo.py" generate --prompt-file /tmp/shot-01.txt --ref "$REF" --aspect 16:9 --out "assets/<slug>-illustrations/01-topic.png"

エンジンレンダリングでは、illo.py generate は画像ごとに JSON 行 （{path, backend, model, id, cost, width, height, label, prompt}。backend は codex、grok、または openrouter で、model／id／cost は OpenRouter 専用です。 CLI 経由の記録（Codex または Grok）では、これらの値は null になります。 --cost を指定しない限り cost は null です（gallery が後から補完します））を出力し、 同じレコードを <out-dir>/manifest.jsonl に追加します。 .path を確認してください。--out と異なる場合があります。エンジンは実際のエンコード形式に 基づいてファイル名を付けます（モデルによっては JPEG のバイト列を返すため、.png を指定しても .jpg として保存されます）。16:9 を指定したのに正方形になっていないか、.width/.height を 確認してください（その場合は再生成します）。Codex／Grok CLI のレンダリングが失敗した場合、 OpenRouter のキーが設定されていても、デフォルトでは停止します。ユーザーが画像ごとの課金を伴う 再試行を明示的に承認した場合に限り、--allow-paid-fallback を追加してください。 --backend openrouter を直接指定するレンダリングと、意図的な Grok の切り抜きへのリダイレクトは、 引き続き直接の経路となるため、このフラグは不要です。 各画像は個別に生成してください。複数のアイデアを 1 つのキャンバスにまとめてはいけません。 デフォルトのアスペクト比は 16:9 です。正方形のソーシャル画像には 1:1、縦長には 9:16／4:5、 X Article のバナー／ヒーロー画像には 1536:640 を使います。X Article バナーの プラットフォーム上の目標サイズは 1536 × 640 px です。通常の画像パイプラインで生成してください。 illo のレンダリングの代わりに、手動で合成したり、切り抜き画像からシーンを再構築したりしてはいけません。 .width/.height を確認し、最終的な後処理は、通常の縦横比と重要な情報をすべて保つ、 歪みのないサイズ変更やトリミングに限ってください。寸法を正確に合わせるために、アートを引き伸ばしたり 押しつぶしたりしてはいけません。ギャラリーに表示するキャプションには --label を渡してください。

セット全体で一人のアーティストが描いたように見せます。 複数画像のセットでは、 最初に品質基準をすべて満たした画像（再ルーティングされた記事セットのヒーロー画像の場合は、 references/article-set-character-reroute.md の主題可読性チェックも通過した画像。 未審査のレンダリングをアンカーにしてはいけません。たとえば地面の色がパレットから外れていたり、 比喩が読み取れなかったりするアンカーを使うと、その失敗がセット全体に波及します）を、 セットのスタイルアンカーにします。セット内の後続画像すべて、およびセット内の画像の再生成ごとに、 キャラクターシートに続けて 2 つ目の --ref として渡してください。これにより、線の太さ、 ハーフトーンの密度、平面的な表現と立体的な表現の扱いに、セット全体で一貫性を持たせられます。 同じ方法で単発画像のスタイルも固定できます。完成済みの例を 2 つ目の --ref として追加してください。 モデルの選択（OpenRouter バックエンドのみ）。 --model と設定の model: はOpenRouter 専用の選択肢です。Codex、Grok CLI、Grok Bot native、Muse native では画像モデルが自動的に選択され、--model は適用されません（references/backends.md）。OpenRouter を使う場合は、--model を指定する前に、またはユーザーが自然言語でモデル名を指定した場合や「最高品質」／「最安値」を求めた場合に、references/models.md を最後まで読んでください。ここには、わかりやすい名前から OpenRouter の ID への対応表、モデルごとの特徴、アスペクト比に関する注意点、404 エラーとフォールバックの処理が記載されています。解決順序は --model > 設定の model > 組み込みのデフォルトです。

ウォーターマーク／クレジット表記（任意、デフォルトではオフ）。 このスキルにはデフォルトのウォーターマークはありません。テキストはユーザーの watermark 設定マップ（設定ファイルから読み込み）または明示的なリクエストからのみ取得されるため、インストール時に他の人のハンドル名が引き継がれることはありません。解決順序、追加するプロンプト行、2 回レンダリングが必要になる注意点については、references/prompt-recipe.md を参照してください。

5b. バッチ処理と比較（役立つ場合のみ）

デフォルトは画像 1 枚です。 ユーザーが選択肢や比較を求めた場合、または重要な制作物でその価値がある場合に限り、複数の画像を生成してください。その前に、各画像のコストを必ず伝えてください。Codex バックエンドではユーザーの Codex クォータを使用し（画像ごとの課金なし）、Grok CLI または Grok Bot native ではユーザーの Grok クォータを使用し、Muse native ではエージェント組み込みの画像ツールを使用し（OpenRouter での課金なし）、OpenRouter バックエンドではユーザーの OpenRouter アカウントに課金されます（通常は画像 1 枚あたり 10 セント未満ですが、モデルによって異なります）。N は小さく抑えてください（2～4）。エンジンのプリミティブを使ってループを制御します。

newrun は新しい実行ディレクトリ（/tmp/illo/<runid>）を出力し、RUN に格納します。ユーザーのリクエストをそのまま（URL、貼り付けられたテキスト、コンセプト）request.txt に記録してください。ギャラリーには出典情報として表示され、誰でもその実行の目的を確認できます。以下の各 generate 行を実際のパスに合わせて個別に実行してください。

SKILL_DIR="<path to this skill>";
RUN=$(python3 "$SKILL_DIR/scripts/illo.py" newrun);
printf '%s' "<the verbatim request>" > "$RUN/request.txt"
# (a) VARIATIONS — same prompt+model, pick-the-best:
python3 .../illo.py generate --prompt-file p.txt --ref <ref> --count 4 --label "draft→ship" --out "$RUN/v.png"
# (b) MODEL COMPARISON — loop the SAME prompt over the chosen models
#     (full OpenRouter ids from references/models.md):
for m in <model-id-1> <model-id-2>; do
  python3 .../illo.py generate --prompt-file p.txt --ref <ref> --model "$m" --label "$m" --out "$RUN/$(basename $m).png"; done
# (c) CONCEPT VARIATIONS — different prompts (different stagings) for one idea:
python3 .../illo.py generate --prompt-file staging-A.txt --ref <ref> --label "as a funnel" --out "$RUN/a.png"
python3 .../illo.py generate --prompt-file staging-B.txt --ref <ref> --label "as a crossing" --out "$RUN/b.png"

python3 "$SKILL_DIR/scripts/illo.py" gallery "$RUN" --title "<the piece or request>" --open
# always pass --title so a saved gallery stays identifiable later;
# add --embed for a single portable file (images inlined)

各 generate は自動的に $RUN/manifest.jsonl に記録されます。gallery は画像ごとのラベル、モデル、寸法、コスト、折りたたみ可能なプロンプトを含む 1 ページにまとめます。プロンプトの表示切り替えは、コンセプトのバリエーションを比較しやすくするうえで重要です（プロンプトが変数です）。ギャラリーは生の出力だけで提示せず、必ずおすすめを添えてください。また、チャットセッションではギャラリーではなく、ラベル付きの候補をチャット内に直接提示してください（手順 7 の提示先の振り分けを参照）。複数モデルを使う場合の失敗は画像ごとに発生します（利用できないモデルでエラーになるのは、そのレンダリングのみです）。残りの画像はそのまま提示してください。

6. QA と反復

すべての画像を references/quality-bar.md に照らして確認してください。マスコットが装飾的なだけになっている、または固定仕様から外れている、パレットに対して本体の色が誤っている、ラベルのテキストが色付きの塗りつぶし上に配置されている、アクセントがキャラクターのアクセント部分と 1～2 個の要素を超えて広がっている、不要なタイトルバーが表示されている、構図がサンプルを模倣している、またはテキストに誤字がある場合は、再生成または編集してください。被写体の大きさは実行ごとに変わります。被写体が小さすぎる場合は再生成してください（JSON の .width/.height を確認します。16:9 を指定したのに正方形の背景になっている場合は再生成してください）。再生成によって以前のレンダリングが置き換えられた場合は、--exclude <superseded label> を指定して（複数回指定可能）、納品用ギャラリーを再構築し、却下した生成物がレビュー用成果物に表示されないようにしてください。

7. 納品 — セッションの媒体に合わせる

必要に応じて、完成品をユーザーの作業ファイルの近くにコピーしてください。頼まれていない限り、既存のアセットを上書きしないでください。ファイル名が役割を示します — ドキュメントを添付した後も残る唯一のメタデータなので、ファイル名だけで内容がわかるようにしてください。ヒーロー画像には 00-hero-<slug>.png、続いて、作品内の順序に沿った各セクションのアンカーには 01-<section-slug>.png、02-<section-slug>.png、…を使用します（assets/<slug>-illustrations/）。そのうえで、画像の枚数、使用したパレット、特に優れた画像と任意の画像を報告してください。複数画像を作成した場合は、配置マップも添えてください。画像ごとに1行で、ファイル名、役割（ヒーロー、またはどのセクションの後に置くか）、伝えるアイデアを記載します。これにより、ユーザーは配置を考え直すことなく、各ファイルを適切な場所に置けます。このセッションで実際に表示できる方法で、画像そのものを渡してください。

• ファイルシステムを使うセッション（IDE／ターミナルエージェント — Claude Code、Codex、Cursor）：各完成品の絶対パスを報告してください（エンジンの JSON の .path はすでに絶対パスです）。複数画像を生成した場合は、ギャラリーも表示してください。ディスク上のファイルがすでにオリジナルです。Hermes ゲートウェイトークンであり、他のランタイムでは文字列としてノイズになる [[as_document]] は、ここでは決して出力しないでください。ランタイムに独自のチャット内ファイル配信機能がある場合は、それを使ってください。

• Grok Bot のネイティブセッション：Grok Bot の内蔵画像ツールから返されたファイルを、チャット内でインラインまたは添付ファイルとして配信し、エンジンのレンダリングで .path が使われるのと同じ用途で、保存先のファイルパスも記載してください。返されたファイルがこの転送方法でのオリジナルです。取得するためだけに、ユーザーに OpenRouter の設定を求めないでください。

• Muse のネイティブセッション：ネイティブ画像ツールから返されたファイルを、チャット内で sandbox://workspace/... リンクとして配信し、エンジンのレンダリングで .path が使われるのと同じ用途で、保存先のファイルパスも記載してください。配信した画像はすべて illo.py record（切り抜き画像の場合は keyout）で記録し、実行の manifest.jsonl とギャラリーが完全な状態になるようにしてください。返されたファイルがこの転送方法でのオリジナルです。取得するためだけに、ユーザーに OpenRouter の設定を求めないでください。

• チャットセッション（ユーザーがメッセージング環境 — Telegram／Discord／WhatsApp 上の Hermes、またはメディアの配信で劣化が起きるその他のチャット環境 — を利用しており、ローカルファイルを開けない場合）：パスだけでは納品として不十分です。画像をチャット内に届け、完成品はオリジナルファイルとして送信する必要があります。プラットフォームの写真送信では画像が再圧縮されます。これはリソグラフの粒子、ハーフトーンの質感、インク層のずれ、細かな手描き文字を損なう原因そのものです。そのため、完成品はドキュメント添付ファイルとして送信してください。Hermes では、各完成品に明示的な MEDIA: 添付タグを付けてください。タグは MEDIA: の直後に絶対パスをスペースなしで続けたものです。また、同じ返信内にリテラルのディレクティブ [[as_document]] を含めてください。完成品に絶対パスだけを記載する方法には頼らないでください。パスだけでは、添付ファイルとして送信されず、文字列としてユーザーに表示されることがあります。

  MEDIA:/absolute/path/to/final.jpg
  [[as_document]]
  

  候補／オプションの提示では、手早く見比べるのに便利な場合、通常のインライン写真送信を使ってもかまいません。その場合は「プレビュー — オリジナルファイルは後ほど送信」と明記してください。ただし、完成品をその方法で送信することは決してありません。チャットでは HTML ギャラリーを省略してください。ユーザーが簡単に開いたりホストしたりする方法がないためです。ラベルを付けた完成品をおすすめと一緒にテキストで直接送信してください。gallery --embed（ファイルが1つで完結する形式）の作成は、持ち運び可能な成果物を明示的に求められた場合に限り、[[as_document]] を付けて配信してください。

チャットセッションで最後に返信する前に、次の点を確認してください。

• 各完成品のパスが、指定した --out ではなく、エンジンの JSON の .path に由来していること（実際の拡張子が異なる場合があります）。
• 各完成品に対して、返信内に明示的な MEDIA:/absolute/path 添付タグがあること。
• プレビューのみの場合を除き、返信に [[as_document]] が含まれていること。
• 却下した候補や再生成した候補が配信対象から除外されていること。
• 実装に関する余計な情報を加えず、何を作成したかをテキストで説明していること。キャラクター、パレット、最も優れた完成品、複数画像の場合は配置マップ（どのファイルがヒーローか、どのファイルがどのセクションの後に続くか）を記載してください。

出力の規律

生成前の計画は、短く具体的にします。生成後は画像に語らせ、作ったものとその場所を報告します。スタイル論は語りません。ラベルは少なく短くします。画像に入れる言葉が少ないほど、より確実に描画されます。

ファイルの要約をするのではなく、作業をしている人のように話します。チャットでは、ワークフローの手順や専門用語を決して語りません。doctor、preflight、provenance、register、saying bar、thesis、backend、「doctor's green」などです。状況を伝える場合も、手順を唱えるような言い方ではなく、普通の言葉で伝えます。サプライズモードで名前のないキャラクターが選ばれたら、英語で一度だけ、わかりやすくキャラクターを紹介します（パック名とそのキャラクターが何かを示します。「Inch, the chalk inchworm」のようにします）。その後にセリフを見せて、どれがよいか尋ねます。名前だけで状況を伝えたり（「Inch.」）、「Still Inch」と言ったり、「にどれを描いてもらう？」と尋ねたりしないでください。ユーザーに伝えるのは、結果――キャラクター、セリフ／画像、作ったもの――であり、手順ではありません。