/pixel-asset-gen
ドット絵ワークスペース用のキャラクタースプライトを、codexのimage_genに指示して生成する手順。 承認済みシートを土台にしたidentity差し替え、10行の意味的一貫性、実画面プレビュー、 runtime反映前の承認までを扱う。Animaのpixel_sheet.pngを新規作成・差し替え・修復するとき、 Pixel Workspaceのキャラクターが細い、潰れる、行ごとに別人化する問題を直すときに使う。
$ npx -y skills add xuiltul/animaworks --skill pixel-asset-gen --agent claude-codeHow it fires
How this skill gets triggered: by you, by Claude, or both.
- Fires itselfAuto-invocation. Claude auto-loads it when your prompt matches the work.Auto-invocation is when the right skill fires by itself at the right moment, driven by a FLOW.md router and a hook, instead of you invoking it by name. It is the difference between a skill being installed and a skill actually getting used.Read the full definition →
- You can call itInvoke it directly when you want it.
- Slash command
/pixel-asset-gen
Context preview
The summary Claude sees to decide when to auto-load this skill.
ドット絵ワークスペース用のキャラクタースプライトを、codexのimage_genに指示して生成する手順。 承認済みシートを土台にしたidentity差し替え、10行の意味的一貫性、実画面プレビュー、 runtime反映前の承認までを扱う。Animaのpixel_sheet.pngを新規作成・差し替え・修復するとき、 Pixel Workspaceのキャラクターが細い、潰れる、行ごとに別人化する問題を直すときに使う。
SKILL.md
pixel-asset-gen.SKILL.mdname: pixel-asset-gen
description: >-
ドット絵ワークスペース用のキャラクタースプライトを、codexのimage_genに指示して生成する手順。
承認済みシートを土台にしたidentity差し替え、10行の意味的一貫性、実画面プレビュー、
runtime反映前の承認までを扱う。Animaのpixel_sheet.pngを新規作成・差し替え・修復するとき、
Pixel Workspaceのキャラクターが細い、潰れる、行ごとに別人化する問題を直すときに使う。
Pixel アセット生成 — codexへの指示の出し方
ドット絵ワークスペース（`/app/workspace/pixel/`）のキャラクタースプライトを作る手順。 2026-07-29〜30にフリート全体で確立した方式を記録したもの。実プロンプト全文と後処理の詳細は同ディレクトリの `PIPELINE_reference.md` にある。
前提
- 画像生成は **codexの組み込み `image_gen`** で行う（grokには無い）。指示に「組み込みの
image_gen ツールを使う。SVG/HTML/CSSでの代替は不可」と明記しないと、勝手にSVGで代替される
- スプライトは **384×960**（96×96フレーム × 4列 × 10行）、透過PNG、アルファ2値。
行順は idle / working / thinking / talking / walk_down / walk_up / walk_side / sleeping / success / error（正本は `server/static/workspace/pixel/CONTRACT.md`）
- 実名アセットは**リポジトリに置かない**。配置先は `<data_dir>/animas/<name>/assets/pixel_sheet.png`
（人間役は `<data_dir>/workspace_pixel/assets/chars/human.png`）
方式は2つあり、使い分ける
| 状況 | 方式 | | --- | --- | | 基準キャラを新しく作る（1体目・画風を決める） | ゼロから生成。1枚の種で画風の承認を取ってから10行に展開 | | 2体目以降・フリートへ展開する | **承認済みシートを土台にした「キャラ差し替え」** |
**2体目以降を独立生成してはいけない。** キャラごとに顔の大きさがバラバラになり、 オフィスに並べた瞬間に不揃いだと分かる（フリート全体で実際に失敗して作り直した）。
キャラ差し替え方式の手順（これが本題）
0. 正本とidentityを固定する
- 形状・ポーズ・ドット密度の正本は、現在承認済みのmio
`~/.animaworks/animas/mio/assets/pixel_sheet.png` とする。開始時にSHA-256を記録する。
- 対象Animaの `assets/prompt.txt`、`avatar_chibi.png`、`avatar_bustup.png` を読み、
髪型、髪色、瞳、髪飾り、服装を1つのidentity仕様へ確定する。
- 参照同士が矛盾する場合は多数一致と明示記述を優先し、解消できなければ生成前に人間へ確認する。
- identity仕様は10行40フレーム共通の不変条件である。状態によって髪丈、髪飾り、瞳、服装を変えない。
1. 土台を作る — ここが成否を分ける
承認済みシートを行ごとに切り出し、**全10行を例外なくPOINTで400%拡大し**、透明部分をマゼンタで埋めた 1536×384の画像**を編集対象にする。
magick <基準シートの行ストリップ>.png \
-filter point -resize 400% \
-background '#FF00FF' -alpha background -alpha remove -alpha off \
<作業dir>/base_row0_idle_x4_magenta.png
384×96のまま渡すと**モデルが顔・髪・体型を再解釈する**。idleだけでなく全10行で必ず400%版を渡す。 過去のMei生成では後半行が低解像度入力へ戻り、行ごとに長髪とボブが混在したため、低解像度入力は不合格とする。
2. image_genへの指示
1行につき1回呼ぶ。入力画像はこの順で3枚:
1. 上で作った400%＋マゼンタの土台（＝編集対象） 2. そのキャラの `avatar_chibi.png`（全身・服装の同定） 3. そのキャラの `avatar_bustup.png`（顔・色の同定）
プロンプトは `precise-object-edit` 構成で書く。全文は `PIPELINE_reference.md` にあるが、要点は:
- Primary request: **Image 1 を編集する。キャラの同一性だけを差し替え、レイアウト・
スケール・シルエット・アニメーション・ピクセルグリッドは Image 1 のまま**
- Composition: 4コマそれぞれの**ポーズ・向き・体の大きさ・肩幅・頭頂の高さ・
露出した顔の大きさ・顔の中心・目鼻口の位置と間隔**を維持。**顔や頭を大きくするな**
- Constraints: 目・眉・鼻・口・頬は小さく分離した読み取れるドットの塊のまま。
**顔（目・鼻・口・頬）に新しい暗色の点・影・輪郭・髪の毛・孤立ピクセルを重ねるな**。 暗い髪は顔の境界からはっきり分離させる
- Scene: 背景は**完全に均一な #FF00FF のみ**（影・グラデーション・床・照明変化を入れない）
- Avoid: black blobs, stray dark pixels, facial dirt, 机・椅子・モニタ・吹き出し・文字・影
- Identity lock: 確定した髪丈、前髪、髪飾りの側、両目の色、服色を文章で毎行繰り返す。
「Images 2 and 3のどちらかを自由に選ぶ」とは書かない
3. 変えてよいもの / だめなもの（指示書に必ず表で書く）
| 変えてよい | 1ドットも変えてはいけない | | --- | --- | | 髪型・髪の長さ・髪色・前髪・髪飾り | 顔（肌の露出部分）の大きさと位置、目鼻口の配置 | | 瞳の色、眉の形 | 頭頂の高さ、顔の中心x、肩の位置と幅、体の大きさ | | 服装（色・形・襟・アクセサリ） | 4コマそれぞれのポーズと動きの内容 | | 肌の色の微調整 | フレーム内の立ち位置、ドットの粒度、輪郭線の太さ |
「髪を増やしたので顔も大きくした」は不合格、と明記する。
4. 透過処理 — 暗色キャラを壊さないためのガード
抜き色は **`#FF00FF` 固定。緑背景は禁止**（despillで肌や淡色の服に緑が混ざる事故が起きた）。
暗色（黒髪・ダークネイビーのスーツ）が背景と誤判定されて欠損する事故も起きたので、 必ず次のガードを入れる。実装は `.claude/skills/pixel-asset-gen/scripts/process_generated_row.py` にある。
- 半透明画素の比率が1.5%を超えたら自動キーの結果を捨て、高彩度マゼンタだけを透明化する
- **暗色・黒に近いRGBは透明化しない**
- 縮小で生じた近黒色の緑/マゼンタ色相は透明化せず `max(r,g,b)` のグレーへ中和する
（透明化すると黒髪やスーツに穴が開く）。キャラ本来の緑眼などは中和しない
- 最後にアルファを `a >= 128 ? 255 : 0` で2値化する
5. 96×96への縮小
固定倍率にしない（モデル出力の寸法は一定でない）。基準シートの各コマの不透明bboxを取り、 生成スプライトを**BOXフィルタでそのbboxサイズに1回だけ縮小**して、同じ座標に整数配置する。 これで位置とサイズが基準に一致する。posterize等の色数削減後処理は禁止（顔が潰れる）。
生成後にシート全体または各フレームへ一律の横・縦補正を追加してはいけない。 特に非等方の `85%x100%` 等を最終検証後に掛けることを禁止する。寸法不良はその行を再生成して直す。
検証
# 基準シートとの突き合わせ（キャラ差し替え方式ではこれが主）
python3 .claude/skills/pixel-asset-gen/scripts/compare_to_reference.py <生成シート> <基準シート>
合否に使うのは次の3つ:
- **頭頂y・顔中心x が基準±1px** — ずれると席の中でキャラが動いて見える
- 頭部幅は±10pxまで許容（髪型が変われば正当に変わる）
- **面積比（不透明画素数の比）0.75〜1.35** — 外れたら透過処理でキャラが削れたか背景が残っている
**顔の大きさは数値で測れない。** 色で肌を判定すると明るい髪色やクリーム色の服を肌と 誤検出する。土台を編集する方式なら自動的に揃うので、最終判断は比較画像の目視で行う。
そして最重要: **codexに各行の96px画像を `view_image` で自分の目で確認させる**。 「顔に黒い塊やゴミ画素が無いこと」は数値検査では検出できず、これで8体の不良を潰した。
機械検査の合格はidentityの合格を意味しない。全40フレームについて、確定した髪型・髪丈・ 髪飾りの側・瞳色・服色を原寸と400%で確認する。行ごとの一覧だけでなく、各行1コマ目を 順番に切り替える遷移GIFで「状態変更時に別人化・伸縮・ジャンプしないこと」を検査する。
最終候補は最初に `~/work/_tmp/YYYYMMDD_<name>アセット再生成/` へ保存し、比較シート、 全行GIF、遷移GIF、検査ログを添える。人間の目視承認前にruntimeの `pixel_sheet.png` を差し替えない。
委譲の実務
- 10体を超える規模なら3〜4体ずつに分けて複数セッション並列（`run_codex.sh -C <作業dir> -p <計画書>`）。
1体あたり10回の画像生成で15〜25分が目安
- 計画書は自己完結させ、共通仕様は別ファイル（SPEC）にして「最初に必ず読む」と書く
- **成功したセッションに手順を書き出させてから他へ展開する**のが有効だった。
セッションごとに後処理の実装が違い、品質差が出る
- セッションがハングしても成果物は出来ていることがある。`check_run.sh` の STALLED を
見たら、まず出力ファイルの検証をしてから再実行を判断する
着席構図の制約（アセット設計に直結）
エンジンは着席キャラを机の天板でクリップするため、**フレーム上端から78pxしか画面に出ない** （実測値。可視範囲 = クリップ線 − (spriteY − 96)）。
- **手を使うモーションは成立しない**。workingは肩の上下・上体の前傾・前髪の揺れで表現する。
手を机の高さに描くと隠れて静止画に見え、机より上に出すと宙に浮いて不自然になる
- thinking（顎に手）・error（頬に手）・success（万歳）は手が顔の高さなので問題ない
- 背景側で机より上に飛び出す前景物（背の高いモニタ等）は
`office_bg_slots.json` の `front_rects` で指定する（CONTRACT.md参照）
候補完成後は実際のPixel Workspaceでも確認する。着席時はフレーム上端から約78pxしか見えないため、 workingの動作、thinkingの顎手、successの腕、errorの頬手が机のクリップ後も読めることを確認する。
Read more
name: pixel-asset-gen description: >- ドット絵ワークスペース用のキャラクタースプライトを、codexのimage_genに指示して生成する手順。 承認済みシートを土台にしたidentity差し替え、10行の意味的一貫性、実画面プレビュー、 runtime反映前の承認までを扱う。Animaのpixel_sheet.pngを新規作成・差し替え・修復するとき、 Pixel Workspaceのキャラクターが細い、潰れる、行ごとに別人化する問題を直すときに使う。
Pixel アセット生成 — codexへの指示の出し方
ドット絵ワークスペース（`/app/workspace/pixel/`）のキャラクタースプライトを作る手順。 2026-07-29〜30にフリート全体で確立した方式を記録したもの。実プロンプト全文と後処理の詳細は同ディレクトリの `PIPELINE_reference.md` にある。
前提
- 画像生成は **codexの組み込み `image_gen`** で行う（grokには無い）。指示に「組み込みの
image_gen ツールを使う。SVG/HTML/CSSでの代替は不可」と明記しないと、勝手にSVGで代替される
- スプライトは **384×960**（96×96フレーム × 4列 × 10行）、透過PNG、アルファ2値。
行順は idle / working / thinking / talking / walk_down / walk_up / walk_side / sleeping / success / error（正本は `server/static/workspace/pixel/CONTRACT.md`）
- 実名アセットは**リポジトリに置かない**。配置先は `<data_dir>/animas/<name>/assets/pixel_sheet.png`
（人間役は `<data_dir>/workspace_pixel/assets/chars/human.png`）
方式は2つあり、使い分ける
| 状況 | 方式 | | --- | --- | | 基準キャラを新しく作る（1体目・画風を決める） | ゼロから生成。1枚の種で画風の承認を取ってから10行に展開 | | 2体目以降・フリートへ展開する | **承認済みシートを土台にした「キャラ差し替え」** |
**2体目以降を独立生成してはいけない。** キャラごとに顔の大きさがバラバラになり、 オフィスに並べた瞬間に不揃いだと分かる（フリート全体で実際に失敗して作り直した）。
キャラ差し替え方式の手順（これが本題）
0. 正本とidentityを固定する
- 形状・ポーズ・ドット密度の正本は、現在承認済みのmio
`~/.animaworks/animas/mio/assets/pixel_sheet.png` とする。開始時にSHA-256を記録する。
- 対象Animaの `assets/prompt.txt`、`avatar_chibi.png`、`avatar_bustup.png` を読み、
髪型、髪色、瞳、髪飾り、服装を1つのidentity仕様へ確定する。
- 参照同士が矛盾する場合は多数一致と明示記述を優先し、解消できなければ生成前に人間へ確認する。
- identity仕様は10行40フレーム共通の不変条件である。状態によって髪丈、髪飾り、瞳、服装を変えない。
1. 土台を作る — ここが成否を分ける
承認済みシートを行ごとに切り出し、**全10行を例外なくPOINTで400%拡大し**、透明部分をマゼンタで埋めた 1536×384の画像**を編集対象にする。
magick <基準シートの行ストリップ>.png \ -filter point -resize 400% \ -background '#FF00FF' -alpha background -alpha remove -alpha off \ <作業dir>/base_row0_idle_x4_magenta.png
384×96のまま渡すと**モデルが顔・髪・体型を再解釈する**。idleだけでなく全10行で必ず400%版を渡す。 過去のMei生成では後半行が低解像度入力へ戻り、行ごとに長髪とボブが混在したため、低解像度入力は不合格とする。
2. image_genへの指示
1行につき1回呼ぶ。入力画像はこの順で3枚:
1. 上で作った400%＋マゼンタの土台（＝編集対象） 2. そのキャラの `avatar_chibi.png`（全身・服装の同定） 3. そのキャラの `avatar_bustup.png`（顔・色の同定）
プロンプトは `precise-object-edit` 構成で書く。全文は `PIPELINE_reference.md` にあるが、要点は:
- Primary request: **Image 1 を編集する。キャラの同一性だけを差し替え、レイアウト・
スケール・シルエット・アニメーション・ピクセルグリッドは Image 1 のまま**
- Composition: 4コマそれぞれの**ポーズ・向き・体の大きさ・肩幅・頭頂の高さ・
露出した顔の大きさ・顔の中心・目鼻口の位置と間隔**を維持。**顔や頭を大きくするな**
- Constraints: 目・眉・鼻・口・頬は小さく分離した読み取れるドットの塊のまま。
**顔（目・鼻・口・頬）に新しい暗色の点・影・輪郭・髪の毛・孤立ピクセルを重ねるな**。 暗い髪は顔の境界からはっきり分離させる
- Scene: 背景は**完全に均一な #FF00FF のみ**（影・グラデーション・床・照明変化を入れない）
- Avoid: black blobs, stray dark pixels, facial dirt, 机・椅子・モニタ・吹き出し・文字・影
- Identity lock: 確定した髪丈、前髪、髪飾りの側、両目の色、服色を文章で毎行繰り返す。
「Images 2 and 3のどちらかを自由に選ぶ」とは書かない
3. 変えてよいもの / だめなもの（指示書に必ず表で書く）
| 変えてよい | 1ドットも変えてはいけない | | --- | --- | | 髪型・髪の長さ・髪色・前髪・髪飾り | 顔（肌の露出部分）の大きさと位置、目鼻口の配置 | | 瞳の色、眉の形 | 頭頂の高さ、顔の中心x、肩の位置と幅、体の大きさ | | 服装（色・形・襟・アクセサリ） | 4コマそれぞれのポーズと動きの内容 | | 肌の色の微調整 | フレーム内の立ち位置、ドットの粒度、輪郭線の太さ |
「髪を増やしたので顔も大きくした」は不合格、と明記する。
4. 透過処理 — 暗色キャラを壊さないためのガード
抜き色は **`#FF00FF` 固定。緑背景は禁止**（despillで肌や淡色の服に緑が混ざる事故が起きた）。
暗色（黒髪・ダークネイビーのスーツ）が背景と誤判定されて欠損する事故も起きたので、 必ず次のガードを入れる。実装は `.claude/skills/pixel-asset-gen/scripts/process_generated_row.py` にある。
- 半透明画素の比率が1.5%を超えたら自動キーの結果を捨て、高彩度マゼンタだけを透明化する
- **暗色・黒に近いRGBは透明化しない**
- 縮小で生じた近黒色の緑/マゼンタ色相は透明化せず `max(r,g,b)` のグレーへ中和する
（透明化すると黒髪やスーツに穴が開く）。キャラ本来の緑眼などは中和しない
- 最後にアルファを `a >= 128 ? 255 : 0` で2値化する
5. 96×96への縮小
固定倍率にしない（モデル出力の寸法は一定でない）。基準シートの各コマの不透明bboxを取り、 生成スプライトを**BOXフィルタでそのbboxサイズに1回だけ縮小**して、同じ座標に整数配置する。 これで位置とサイズが基準に一致する。posterize等の色数削減後処理は禁止（顔が潰れる）。
生成後にシート全体または各フレームへ一律の横・縦補正を追加してはいけない。 特に非等方の `85%x100%` 等を最終検証後に掛けることを禁止する。寸法不良はその行を再生成して直す。
検証
# 基準シートとの突き合わせ（キャラ差し替え方式ではこれが主） python3 .claude/skills/pixel-asset-gen/scripts/compare_to_reference.py <生成シート> <基準シート>
合否に使うのは次の3つ:
- **頭頂y・顔中心x が基準±1px** — ずれると席の中でキャラが動いて見える
- 頭部幅は±10pxまで許容（髪型が変われば正当に変わる）
- **面積比（不透明画素数の比）0.75〜1.35** — 外れたら透過処理でキャラが削れたか背景が残っている
**顔の大きさは数値で測れない。** 色で肌を判定すると明るい髪色やクリーム色の服を肌と 誤検出する。土台を編集する方式なら自動的に揃うので、最終判断は比較画像の目視で行う。
そして最重要: **codexに各行の96px画像を `view_image` で自分の目で確認させる**。 「顔に黒い塊やゴミ画素が無いこと」は数値検査では検出できず、これで8体の不良を潰した。
機械検査の合格はidentityの合格を意味しない。全40フレームについて、確定した髪型・髪丈・ 髪飾りの側・瞳色・服色を原寸と400%で確認する。行ごとの一覧だけでなく、各行1コマ目を 順番に切り替える遷移GIFで「状態変更時に別人化・伸縮・ジャンプしないこと」を検査する。
最終候補は最初に `~/work/_tmp/YYYYMMDD_<name>アセット再生成/` へ保存し、比較シート、 全行GIF、遷移GIF、検査ログを添える。人間の目視承認前にruntimeの `pixel_sheet.png` を差し替えない。
委譲の実務
- 10体を超える規模なら3〜4体ずつに分けて複数セッション並列（`run_codex.sh -C <作業dir> -p <計画書>`）。
1体あたり10回の画像生成で15〜25分が目安
- 計画書は自己完結させ、共通仕様は別ファイル（SPEC）にして「最初に必ず読む」と書く
- **成功したセッションに手順を書き出させてから他へ展開する**のが有効だった。
セッションごとに後処理の実装が違い、品質差が出る
- セッションがハングしても成果物は出来ていることがある。`check_run.sh` の STALLED を
見たら、まず出力ファイルの検証をしてから再実行を判断する
着席構図の制約（アセット設計に直結）
エンジンは着席キャラを机の天板でクリップするため、**フレーム上端から78pxしか画面に出ない** （実測値。可視範囲 = クリップ線 − (spriteY − 96)）。
- **手を使うモーションは成立しない**。workingは肩の上下・上体の前傾・前髪の揺れで表現する。
手を机の高さに描くと隠れて静止画に見え、机より上に出すと宙に浮いて不自然になる
- thinking（顎に手）・error（頬に手）・success（万歳）は手が顔の高さなので問題ない
- 背景側で机より上に飛び出す前景物（背の高いモニタ等）は
`office_bg_slots.json` の `front_rects` で指定する（CONTRACT.md参照）
候補完成後は実際のPixel Workspaceでも確認する。着席時はフレーム上端から約78pxしか見えないため、 workingの動作、thinkingの顎手、successの腕、errorの頬手が机のクリップ後も読めることを確認する。
No one can do anything alone. So I built an organization. A framework that treats AI agents not as one-off “tools,” but as team members who keep working with persistent memory.
Repo: xuiltul/animaworks