| name | character-to-codex-pet |
| description | 既存キャラクター画像を、承認制でピクセルアートの正準画像へ変換し、3状態パイロット、クロマ前処理、状態間ジオメトリ検証、9状態生成、遷移QA、仮配置、アプリ内確認、ロールバック可能な正式配置まで行う。キャラクターからCodexペットを作る依頼に加え、ジャンプで小さくなる、状態ごとに身長が変わる、足元が跳ねる、クロマ縁が出る、アニメーションを修復したい依頼で使用する。 |
既存キャラクターからCodexペットを作る
既存画像をいきなり全状態へ展開しない。承認済みの正準画像と192x208の正準セルを固定し、idle・running-right・jumpingの3状態パイロットで生成品質を証明してから残りを作る。アプリ内確認が終わるまで中間素材を保持する。
依存スキル
- 最初に
${CODEX_HOME:-$HOME/.codex}/skills/.system/imagegen/SKILL.md を最後まで読み、通常は組み込みimage_genを使う。
hatch-petのインストール済みパス、または ${CODEX_HOME:-$HOME/.codex}/vendor_imports/skills/skills/.curated/hatch-pet を探し、対象SKILL.mdを最後まで読む。- 生成は
imagegen、行準備・抽出・合成・基本検証はhatch-pet、このスキルのスクリプトは正準セル、クロマ前処理、状態間ジオメトリ、遷移QA、安全配置を担当する。
SKILL_ROOTはこのSKILL.mdを含むディレクトリの絶対パスとして扱い、同梱スクリプトは$SKILL_ROOT/scripts/...で実行する。
絶対ルール
- ユーザーが対象を特定して明示的に承認するまで、基準画像を正準化しない。
- 正準画像、正準セル、元画像、状態別レイアウトガイドを各行生成へ添付する。テキストだけで行を生成しない。
- 生成行でカメラのズーム、引き、キャラクター自体の縮小によって動きを表現させない。
- 行ごとのクロマ前処理を必須とし、元の
decoded/を上書きしない。
- フレーム単位で身長を揃えない。状態行ごとに共通倍率を1つだけ使い、屈みや足開きなどのポーズ差を維持する。
- 通常1.12倍、ジャンプ1.15倍を超える補正が必要なら、その行を再生成する。既存資産の修復だけは
--allow-large-correctionを明示できる。
- 状態単体GIFだけで完成判定しない。
idle→jumping→idleとidle→failed→idleを必ず確認する。
- アプリ内確認前に
prompts/、decoded/、透明化済み行、抽出フレーム、manifestを削除しない。
- 正式ペットを直接上書きしない。候補パッケージを作り、ユーザーのアプリ内承認後にバックアップ付きで昇格する。
- 問題がある場合は最小の行だけを修復する。
- 現行契約は9状態、8列×9行、
1536x1872だけとする。追加行や別バージョンを推測せず、Codex App側の契約を別途確認できた場合だけ拡張する。
既存ペットを修復する場合は元runを直接変更せず、兄弟repair runを作る。正常行はそのまま保持し、不合格行全体だけを再生成する。詳細はproduction-contracts-ja.mdの修復契約に従う。
進捗表示
次のゲートを表示し、常に1つだけを進行中にする。
- 入力とキャラクター固定条件を確定する。
- ピクセルアート基準画像を作り、承認を得る。
- 正準セルと3状態パイロットを検証する。
- 残り6状態を生成する。
- 全状態を前処理・正規化・合成・QAする。
- 候補をアプリで確認する。
- 正式反映し、必要なら中間素材を整理する。
実行手順
1. 入力とrunを準備する
参照画像、ペット名、ID、説明、維持する顔・体型・配色・服装・模様・小物、削除可能な背景・文字・影、ピクセル密度を確定する。判断できる項目は推定し、短く報告する。
hatch-petのprepare_pet_run.pyをpixelスタイルで実行する。生成されたpet_request.json、imagegen-jobs.json、プロンプト、レイアウトガイドを正とする。
2. 基準画像を承認する
既存画像を編集対象とするstyle-transferとして、prompts-ja.mdの基準画像契約を使う。候補は別ファイルで保存し、192x208相当でも顔と輪郭が読めるか確認する。
承認された画像をreferences/canonical-base.pngへ固定する。次に次のスクリプトでセル寸法の正準画像を作る。
python "$SKILL_ROOT/scripts/prepare_canonical_cell.py" \
--input <run>/references/canonical-base.png \
--output <run>/references/canonical-cell.png \
--report-json <run>/qa/canonical-cell.json
canonical-cell.pngを全行の生成入力へ追加する。
3. 3状態パイロットを通す
最初にidle、running-right、jumpingだけを生成する。各行へ正準画像、正準セル、元画像、状態別レイアウトガイドを添付する。
生成後、production-contracts-ja.mdのパイロット工程を実行する。
preprocess_chroma_rows.pyで非破壊の透明化・デスピルを行う。hatch-petで3行だけをstable-slots抽出する。normalize_pet_geometry.pyを通常モードで実行する。- 大幅補正、身長、足元、ジャンプ幅のハードゲートを通す。
- パイロットのコンタクトシートと遷移GIFを目視する。
1件でも不合格なら該当行を再生成する。パイロットが通るまで残りを作らない。
4. 残りを生成する
running-rightが左右反転に安全なら専用スクリプトでrunning-leftを派生する。文字、ロゴ、左右固有模様、小物方向、光源の意味が壊れる場合は個別生成する。
続けてwaving、jumping以外の未生成行、failed、waiting、running、reviewを生成する。各行は独立したimagegen呼び出しにする。
サブエージェントへ委任する場合、許可が曖昧なら開始前に確認する。同時生成は最大2行、各担当は1行だけを扱い、親がmanifest、正準画像、合成、修復を管理する。
5. 全状態を最終化する
全行へクロマ前処理を行い、stable-slotsで抽出する。抽出した損失なしPNGフレームを入力としてnormalize_pet_geometry.pyを実行する。完成WebPを再入力に使わない。
正規化後フレームからアトラス、検証JSON、コンタクトシート、状態別GIFを作る。さらにrender_transition_previews.pyで状態遷移GIFを作る。qa-ja.mdを全項目確認し、HighまたはMediumがあれば該当行だけ修復する。
6. 仮配置してアプリ確認する
package_pet_safely.py stageでrun内に候補パッケージを作る。この段階では${CODEX_HOME:-$HOME/.codex}/pets/<pet-id>を変更しない。
package_pet_safely.py previewで<pet-id>-candidateとして一時配置し、次を実機確認する。正式IDは変更しない。
- idleからjumpingへ切り替わってもキャラクター自体が縮小しない。
- ジャンプ幅が大きすぎない。
- failedで屈んだときはポーズ分だけ自然に小さくなる。
- 左右移動の向き、歩容、身長、足元が自然である。
- クロマ縁、クリップ、状態切り替え時のサイズポップがない。
確認結果をacceptance.jsonとrun summaryへ記録する。未確認の成果物は「暫定完成」と報告し、完成扱いにしない。
7. 正式反映とロールバック
ユーザーがアプリ内で承認した後だけ、次を実行する。
python "$SKILL_ROOT/scripts/package_pet_safely.py" promote \
--candidate-dir <run>/candidate-package \
--confirm-in-app-accepted
既存ペットは${CODEX_HOME:-$HOME/.codex}/pets/.backups/へ退避される。問題があればrollbackを実行する。
正式承認後に限り中間素材を整理する。正準画像、正準セル、最終WebP、検証、ジオメトリレポート、コンタクトシート、状態別GIF、遷移GIF、run summary、候補受付記録は残す。
完了条件
- production-contracts-ja.mdの全ハードゲートを通過している。
- 正準画像と正準セルが保存されている。
- 3状態パイロット合格後に残りを生成している。
- 全9状態で同一性、ピクセル密度、状態意味、身長、足元、透明境界が合格している。
- 状態単体GIFと状態遷移GIFを確認している。
- アプリ内承認が記録されている。
- 正式配置先とバックアップ先を報告している。
