---
name: charakuru-claude-code
description: きゃらくる（Charakuru）キットを Claude Code で動かし、元絵（四面図）から Codex の画像生成と Tripo Studio で3D化して、揺れもの・表情付きの VRM モデルを仕上げるまでの制作ワークフローと落とし穴集。きゃらくる / Charakuru / .charakit（旧名 Chara Kit / ELYTH Avatar Kit）が話題に出たとき、きゃらくるのアプリが出した依頼文（agent-session.mjs begin …）を受け取ったとき、またはきゃらくるで元絵から VRM を作る・Tripo で3D化する・揺れものや表情を付ける作業をするときに使う。
---

# きゃらくる × Claude Code モデル制作ワークフロー

きゃらくる（以下キット）は、元絵から画像と3Dモデルを作り、ユーザーの確認を挟んで VRM まで仕上げるローカルアプリと工程別 Skills のセットです。キットは Codex での作業を前提に書かれています。この Skill は、それを **Claude Code が主担当で回す** ときの役割分担・確認地点・実際にハマった点を、モデル制作（元絵 → 表情付き VRM）の範囲でまとめたものです。

キット内部の手順（依頼文、`agent-session.mjs`、各工程の Skill）は**キットの記述が正**です。この Skill はその上に乗る運用ノウハウで、キットの手順と食い違ったらキットに従ってください。ただしクレジット上限の合意（下記）は、キットの「依頼外の有料処理は確認する」の運用として守ります。キットは更新されるので、作業のたびにキットの `AGENTS.md` と該当工程の `skills/*/SKILL.md` を読み直します。

この Skill の中のパスは、`<skill>` がこの Skill のフォルダ、`<kit>` がキットのルートです（どちらにも `scripts/` があるので混同しない）。

## 役割分担

| 担当 | やること | 理由 |
| --- | --- | --- |
| Claude Code | 依頼文の実行、Blender の自動処理、Tripo Studio のブラウザ操作、検査、保存・登録 | ほぼ全工程。キットの処理はスクリプトと目視判断の組み合わせで、Claude が通しで持つと手戻りが少ない |
| Codex CLI | **画像生成だけ**（`<skill>/scripts/codex_img.sh` で `codex exec` の組み込み image_gen を1回呼ぶ） | Claude Code には画像生成ツールがない。生成以外（判断・合成・検査）は Claude がやる |
| Tripo Studio | 候補生成、セグメンテーション、Smart UV、再テクスチャ、自動リグ | ログイン済みの既存 Chrome タブを Claude in Chrome で操作する。新しいブラウザやセッションは勝手に開かない |
| ユーザー（オーナー） | 参照画像の承認、候補の決定、頭身、動作確認、VRM メタデータ（作者・利用条件）、最終の見た目 | キットの確認地点。加えて **Tripo のクレジット上限を最初に合意する**（上限を超えそうなとき、依頼外のやり直しをするときは止めて確認） |

## 始める前に

[セットアップ](references/setup.md)の確認項目を一通り見ます。特に次の4点は、最初に決めておかないと後で止まります。

- **クレジット予算**: Tripo の残高と、今回使ってよい上限をユーザーに確認し、作業ログに「開始時残高・上限・各操作の消費」を残す。上限内の依頼済みの処理は工程ごとに承認を取り直さない（キットの規則）。上限に近づいたら止めて相談する。
- **画像生成の経路**: `codex` が使えること（`codex exec` で image_gen が呼べること）を1枚生成して確かめる。
- **シェルと Blender**: `<skill>/scripts/*.sh` は bash で動かす（Windows は Git for Windows の Git Bash、macOS は標準の bash でよい）。Blender は `BLENDER` 環境変数に実行ファイルを入れて `"$BLENDER"` で呼ぶ（[セットアップ](references/setup.md)）。
- **作業ドライブ**: Windows では 260 文字のパス制限に当たる。短い作業フォルダ（例 `D:\work\`）を用意し、容量の大きい中間ファイルをどこに置くかユーザーの方針を確認する。

## 工程の進め方

アプリで工程の依頼を出すと依頼文が出ます。Claude はその中の `node ".../scripts/agent-session.mjs" begin URL REQUEST_ID` を最初に実行し、`saved: true` を確認してから、出力の `directory/AGENTS.md` と指定 Skill を読んで作業します。途中は `progress`、完了は `complete`、中断は `fail` で通知し、正本（`project.charakit`）は同じパスのまま更新します。依頼文はアプリ画面のテキストエリアから読み取れます（Chrome の javascript ツールで取得できる）。

| 工程 | Claude がやること | ユーザーの確認地点 | 詳しく |
| --- | --- | --- | --- |
| 元絵 | 四面図を4方向に分けて `refs/` に置き、アプリに登録 | 元絵の選定 | [工程メモ](references/stages.md#元絵) |
| 画像素材 images | 頭（帽子・髪込み）4方向＋Tポーズ体4方向の8枚、全身三面図3枚を Codex で生成し、破綻を直して登録 | **8枚＋三面図を承認**（Tripo 投入前） | [工程メモ](references/stages.md#画像素材) |
| 候補 candidates | Tripo で頭・体を各4候補生成し登録 | 頭・体をそれぞれ選ぶ（Claude は選ばない） | [工程メモ](references/stages.md#3d候補) |
| 素材 materials | セグメンテーション、揺れもの分離、分類、Smart UV、再テクスチャ、組立 | 頭身（位置・サイズ） | [工程メモ](references/stages.md#素材化) |
| リグ rig | Tripo 自動リグの骨配置だけ取り込み、素体ウェイト転送、揺れもの・コライダー設定、自動検査 | 動作確認 | [工程メモ](references/stages.md#リギングと揺れもの) |
| 動作確認 | 標準歩行で破綻を見る。腕が体やスカートに埋まるなら基本姿勢を疑う | VRM の保存（メタデータ） | [工程メモ](references/stages.md#動作確認と-tポーズ補正) |
| 表情 expressions | 目8・眉5を転送して仕上げ、登録。口10は開いた口の試作を見せてから作るか決める | 表情の見た目、口を作るか | [表情制作](references/expressions.md) |
| 表情付き VRM | 表情キーを VRM 1.0 の表情に割り当て、別名の VRM として書き出す | 表情の動作 | [表情付き VRM](references/expressions.md#表情付き-vrm-を別名で書き出す) |

各工程で何かおかしいと感じたら、まず[落とし穴集](references/pitfalls.md)を見てください。実際の制作で起きた症状と原因・直し方を表にしてあります。

## 判断の原則

- **参照画像の承認前に Tripo へ投げない。** 参照画像の破綻（首の太さ、髪の長さの左右差、横顔の比率など）は、3D 化してからでは直せずクレジットが無駄になります。画像を並べてユーザーに見せ、承認をもらってから投げます（キットの確認地点）。クレジットは最初に合意した上限の範囲で使います。
- **破綻の原因を決めつけない。** モーションや Tripo の生成結果が原因に見える症状の多くは、基本姿勢・向き・スケールのずれです。数値で比べてから直します（例: 腕が体に埋まる → VRMA の腕角度とモデルの基本姿勢の腕角度を比較する、`<skill>/scripts/vrma_arm_angles.mjs`）。
- **正本と正式出力を上書きしない。** 派生物（表情付き VRM など）は別名・別フォルダに作ります。`exports/avatar.vrm` はアプリの「VRMを書き出す」でユーザーが保存するものです。
- **OS のダイアログを自動化しない。** 保存先ダイアログなどは、ブラウザ設定（ダウンロード時に毎回確認しない）をユーザーに変えてもらう方が確実です。
- **見た目はユーザーが決める。** 自動検査の合格は技術的に成立したという意味で、見た目の合格ではありません。表情だけは、キットの指示どおり Claude が目視で比較・修正を繰り返します。
- **素材のライセンスを確認する。** 参照画像や外部素材の利用規約を確かめ、VRM のメタデータ（作者・利用条件）は推測で埋めずユーザーに決めてもらいます。

## Blender を背景で動かすときの基本

- Blender は 5.2 以降、VRM Add-on for Blender が必要です。`--factory-startup` でも拡張機能は読み込まれます。
- **呼び出しは `"$BLENDER" -b --factory-startup --python-exit-code 1 --python <script> -- <引数>` の形にする。** `--python-exit-code 1` がないと、スクリプトが例外で止まっても終了コードが 0 になり、失敗を見落とします。
- **VRM データ入りの .blend は、VRM Add-on を有効化してから開く。** 先に開くと、時々 `EXCEPTION_ACCESS_VIOLATION` で落ちます。キットの `<kit>/scripts/mtoon-export.py` の `enable_vrm()` を読み込んで有効化 → `bpy.ops.wm.open_mainfile()` の順にします（`<skill>/scripts/ea_run.py` がこの形）。
- 結果は画像で確かめます。背景レンダー（Workbench / EEVEE）で正面・斜め・横を撮り、コンタクトシート（`<skill>/scripts/contact.py`）にまとめて見ると速いです。
- 画像を扱う Python（Pillow）は、Blender 同梱の Python に `--target` で入れたフォルダを `PYTHONPATH` に通すと、システム Python がない環境でも使えます。

## 完了時の報告

ユーザーへの報告には次を含めます。

- 成果物の場所（正式 VRM、表情付き VRM、作業 Blend）
- 作った表情の内訳（口を見送った場合はそのこと）
- Tripo クレジットの消費と残高
- 見つかった問題と直したこと（原因つき）
- ユーザーにお願いしたいこと（確認、VRM の書き出し、投稿前のチェックなど）