name: live2d-halfbody description: 从一张立绘或一段角色描述，做出能在 VTube Studio 里直播用的半身 Live2D 皮套，不用手动建模、不开 Cubism Editor：图像模型出图、See-through 拆层、代码补细节和绑定、自查后装进 VTS。默认带小角度转头、歪头、身体跟随、呼吸、眨眼和单眼眨眼、口型、四个表情、头发分段摆动（短发、过肩长发或双马尾，刘海可有可无，侧发可别在耳后）、挂件和耳坠摆动、眼镜、招手/摊手/指向三个手势和脸红。用于用户想新做一个皮套（有立绘、只有描述、或已有分层文件）、检查皮套素材、或调整已有角色的动作幅度时。Builds a half-body Live2D avatar for VTube Studio from one character illustration or a text description.

半身皮套：从一张立绘到 VTube Studio

给不想手动建模、不想调网格的人。一张立绘或一段角色描述进去，Agent 一步步做出能在 VTS 里直播用的半身 Live2D 皮套。用户只做三件事：

1. 确认立绘（第 1 步）；
2. 同意把立绘传到 See-through（第 3 步，Hugging Face，备用魔搭）；
3. 在 VTS 里看效果，回复 通过 或 不通过：<现象>（第 5 步）。

其余由 Agent 完成，并在交给用户前自查。

跑一次就有的功能

做不到：大角度转头（要侧脸素材）、全身、手臂跟着摄像头连续动（要分段手臂素材）。产出是 VTS 直接用的 .moc3，不是 Cubism Editor 的工程文件（.cmo3），Editor 打不开。精修级的效果（更细的物理、更多表情、商业级网格）要把 layers-st/ 的图层导进 Cubism Editor 重新绑定。

文件夹

素材/角色名/                 立绘、提示词、变体、See-through 结果、图层
  A0-base.png                定稿立绘
  prompts/                   从 references/提示词/标准/ 复制，填好 [[…]]
  check/                     每张变体的对位检查图
  seethrough.psd             See-through 的原始结果
  seethrough/                拆成每层一张 PNG
  layers/                    自拆的图层：只作 See-through 合成的底，不单独交付
  layers-st/                 最终图层（See-through 合成，含手势和脸红）
  R0-rest.png                最终图层的静止合成，手势和脸红变体的底图
角色/角色名/
  character.json             位置、幅度、图层对照
  标注.png                    character.json 里的位置画在立绘上
  素材检查/  prepared/  build/runtime/  自查/  vts/

步骤

命令都在用户的工作目录（放 素材/、角色/ 的地方）里跑，命令前加 PYTHONPATH=<skill 目录>（如 ~/.claude/skills/live2d-halfbody），Python 才找得到 rigkit。

0. 检查环境

python -m rigkit.doctor

有 ✗ 的先处理完再出图，否则会在出完二十来张图之后才卡住。! 只影响一部分：没有 See-through 令牌时匿名额度不一定够，没有 ffmpeg 时出不了自查短片，没有 Codex 时用其他图像工具出图（见第 2 步）。

1. 立绘 —— 用户确认

把 references/提示词/标准/ 整个复制到 素材/角色名/prompts/，先填好 A0-base.txt 里的 [[…]]（外貌、刘海、两侧头发、头发长短、眼镜、耳坠）。

• 只有描述：照描述填，生成立绘。
• 有立绘：存为 素材/角色名/参考.png，生成时作为参考图附上，得到一张按绑定要求画的版本（脖子露出；有刘海时停在眉毛以上；两侧头发盖住耳朵到下巴为止，或别在耳后；平光、白底、手臂和身体之间留缝）。原图不满足这些要求时，直接拆会在动起来时出问题。

python -m rigkit.variants 素材/角色名 A0-base

没有 Codex 时按第 2 步的“用其他图像工具出图”出 A0。给用户看，用户确认后才往下做。

已有按 图层清单 分好层的文件时，跳到第 4 步。

2. 出图

把 prompts/ 里其余的 [[…]] 换成这个角色的描述；角色没有的部件删掉对应的提示词：帽子或发饰 V1，耳前的侧发 V2，刘海 V3，挂件 V9（S1 里同时删掉那一行，见 出图）。然后：

python -m rigkit.variants 素材/角色名

依次生成 13～17 张“整张图改一处”的变体，每张出对位检查图。偏移 4 px 以内、改动只在该改的地方算合格；不合格删掉重出，同一张最多三次。细节见 出图。

用其他图像工具出图（没有 Codex，或 Agent 自己能出图）：variants 遇到已经有的图只做检查，不重出，所以可以先用别的工具把图出好放进去。

python -m rigkit.variants 素材/角色名 --list

每行一张图：要附的图、提示词文件、出了没有。按顺序一次出一张，附的图标着“还没有”时等它出好：

• 提示词用 prompts/<名>.txt 的全文，不改写；只附列出的那一张图，让工具在它上面改。A0 附参考图，没有参考图时直接生成。
• 工具要能改图：给一张图和提示词，返回改过的同一张图。只能凭文字出新图的工具只能出 A0。
• 存为 素材/角色名/<名>.png，和附的图长宽比相同。不裁、不加边、不抠图、不修补。
• A0 出成正方形；不是 1254×1254 时缩放到这个尺寸（做过的角色都是这个尺寸）。

出完一批，跑一次 python -m rigkit.variants 素材/角色名 出检查图，合格标准同上。第 3 步的手势和脸红同样：--list F1-blush P1-wave P2-explain P3-point。还没用 Codex 以外的工具完整做过一个角色。

3. 拆层 —— 用户同意上传

先用变体自拆，作为合成的底：

python -m rigkit.split 素材/角色名 素材/角色名/layers --pad-top 90

再问用户是否同意把立绘传到 See-through，同意后：

python -m rigkit.seethrough fetch 素材/角色名/A0-base.png 素材/角色名/seethrough
python -m rigkit.seethrough split 素材/角色名 素材/角色名/layers 素材/角色名/layers-st --pad-top 90

fetch 先试 Hugging Face，没跑成再换魔搭（--site hf 或 --site modelscope 指定一个），各用能给的最高分辨率。也可以把网页版、ComfyUI 或自己显卡跑出的 PSD 交给它：fetch 那个.psd 素材/角色名/seethrough。本机装了 See-through 时用 --site local：不传图，不占额度（见“环境”）。

最终图层必须走 See-through：自拆的图层动起来边缘有碎点、被挡住的头发补不全，不单独交付。当天没有额度时，换另一个网站、等第二天，或者用 PSD。

split 会逐条打印它对 See-through 图层做的修正（裁掉画到别处的、挪回归错的配饰、补漏画的部件），规则见 规则 的“See-through 合成”。看 layers-st/拆层总览.png：每层只有自己的东西，静止合成和立绘只差在画风。

闭眼、笑眼是自拆的。它们带进旁边的线或边缘毛躁、同一处改两次还在时，把这两张变体交给 See-through 拆，再跑一次上面的 split，它会改用 See-through 的睫毛层（规则第 103 条）：

python -m rigkit.seethrough fetch 素材/角色名/D5-eyes-closed.png 素材/角色名/seethrough-D5-eyes-closed
python -m rigkit.seethrough fetch 素材/角色名/D6-eyes-smile.png 素材/角色名/seethrough-D6-eyes-smile

传到网站同样先问用户，每张占一次额度。本机跑时加 --site local --head-from 素材/角色名/seethrough，只拆头部。

然后做手势和脸红：

python -m rigkit.extras 素材/角色名 素材/角色名/layers-st        # 写出 R0-rest.png
python -m rigkit.variants 素材/角色名 F1-blush P1-wave P2-explain P3-point
python -m rigkit.extras 素材/角色名 素材/角色名/layers-st        # 加进图层

看 layers-st/手势和脸红.png：每行是静止、变体、模型里打开后的样子，手臂和身体接得上、手的边缘干净才往下做。

4. 生成并自查

python -m rigkit.estimate 素材/角色名/layers-st 角色/角色名 --name 名字
python -m rigkit.check_art 角色/角色名/character.json
python -m rigkit.prepare 角色/角色名/character.json
python -m rigkit.build 角色/角色名/character.json             # 几分钟

• estimate 不覆盖已有的 character.json，写成 character.draft.json；图层改过要重估时，比对后换上。
• 标注.png：脸的椭圆、眼眉鼻嘴、歪头转轴、颈根、肩、腰、发根线不在对的位置时，改 character.json 里对应的数字，重新 prepare 和 build。
• 素材检查/：露底 有品红、原画对照 有成线的红色时，回到第 3 步。透出背景 列出静止时没盖住的地方、手势时变透明的地方，再看 青底.png（静止和各手势放在青色背景上）：白衣服、浅色皮肤处的缺口在白底上看不出。手臂挪开处变透明是正常的，其余回到第 3 步。

自查：

python -m rigkit.preview flips 角色/角色名/build/runtime
python -m rigkit.preview sheet 角色/角色名/character.json 角色/角色名/自查 新版=角色/角色名/build/runtime
python -m rigkit.preview clip 角色/角色名/character.json 角色/角色名/自查/动作.mp4 新版=角色/角色名/build/runtime

翻折三角形应为 0。看放大图和短片里的固定检查区（眉毛和刘海、脸边、下巴和脖子、太阳穴和耳朵、眼角和睫毛、嘴角），有问题先修，再交给用户。有上一版时把上一版放在前面并排比。

再在 VTS 的背景色上，把闭眼、半闭、笑眼、张大嘴、半张嘴、三个手势、左右甩头各渲一张，眼睛、嘴、头发交界放大三到四倍看：用户在 VTS 里最先看到的就是这些画面。

5. 装进 VTS —— 用户验收

python -m rigkit.vts 角色/角色名/character.json --install

新模型可以在 VTS 开着时装；覆盖已装的模型要先退出 VTS，这时保留用户在 VTS 里调过的设置，只补缺的快捷键和映射。VTS 开着又要换新版时，改 vts.name 和 vts.folder 装成新文件夹。

给用户并排图、短片和下面这张清单，回复 通过 或 不通过：<现象>：

调幅度

动作幅度都在 character.json：

幅度按 VTS 半身取景和真人动作判断：正常歪头约 15°，模型只转 3° 就等于没有。改完重新 build。其余字段见 配置说明。

规则

全部规则和来由见 规则。最常被违反的几条：

• 动手前先查 Live2D 的标准做法，说清楚打算怎么做。
• 切图用 See-through，图像模型只补它给不了的细节（表情、被挡住的部分、手势）。
• 只处理有把握的部分：See-through 的图层整块用，代码只做整块的取舍、挪动和按不相连的块分开，不在它的层里按颜色逐像素再切（切出来都毛躁）。要改一处，先和 See-through 原样并排放大比，没有明显更好就不改。
• 新规则先在所有已有角色上量判断依据、定适用范围，改完新旧代码各跑一遍逐层比，不误伤已通过的角色。每条规则写明范围：通用，还是只在某种情况下触发（触发条件、不管哪些情况）。
• 每轮给同尺寸并排图和短片，由人判断；翻折数、像素差只用来排查破面。
• 同一个症状修了三轮还在，停止改代码，改用素材解决。
• 图像模型只派“整张图改一处”，不派“只留一部分”；要的部分由代码用差值算。
• 传图到外部服务前先问用户；账号和 token 由用户自己注册、自己填，不在对话里复述 token。
• 安装时不覆盖用户的 vtube.json，覆盖已装模型时 VTS 要先退出。

环境

• Python 3.10+：pip install -r <skill 目录>/requirements.txt（系统 Python 不让装时建一个虚拟环境）。出短片要 ffmpeg。
• Codex 命令行（出图）：ChatGPT 桌面版自带，或单独安装的 codex（在 PATH 里即可），登录 ChatGPT 账号；都不是时把环境变量 CODEX 指向它。没有 Codex 时用其他能改图的图像工具，见第 2 步。
• See-through（拆层），两个网站跑的是同一个模型，至少准备一个：
  • Hugging Face（首选，几分钟一次，最高 1280）：不登录时每天的免费显卡时间不一定够跑一次；用户注册免费账号、建一个 Read token，放进环境变量 HF_TOKEN 或 ~/.cache/huggingface/token（hf auth login 存的位置），每天约 1～2 次。
  • 魔搭 ModelScope（备用，免费，最高 1536）：用户注册账号、建一个访问令牌，放进环境变量 MODELSCOPE_API_TOKEN 或 ~/.cache/modelscope/token。要排队，一次可能半小时。1536 的头发轮廓和眼睛比 1280 更接近原画。
  • 本机（可选，不传图，不限次数）：在 Apple 芯片、24 GB 内存上验证过，1280 整张约 21 分钟，只拆头部约 9 分钟；第一次运行下载约 13 GB 模型。装好后把环境变量 SEETHROUGH_DIR 指向它，装法见 出图 的“本机跑 See-through”。
• VTube Studio（Steam 版）。
• Live2D Cubism Core（预览、自查、图标要用）：装了 Cubism Editor 时自动找到；否则下载 Cubism SDK for Native，把环境变量 CUBISM_CORE 指向其中的 Core 动态库。Core 按 Live2D 的许可使用，不随本 skill 分发。

macOS 上验证过；Windows 未验证。

已知问题

• 摄像头手势（张开手掌 = 招手、双手张开 = 摊手、竖食指 = 指向）：第一个角色能触发，第二个角色配置逐字段相同却不触发，原因未查明。快捷键 N5～N7 不受影响。
• 静止时是 See-through 画的样子，比原画软一点，睫毛、发梢描边的细节少一些。
• 戴眼镜、镜框紧挨双眼皮时，See-through 会丢掉双眼皮线，在睫毛上沿画一道浅灰带，按原样保留。
• 眼尾贴着脸颊和耳朵之间的轮廓线时（毛线帽），自拆的闭眼和笑眼图层会带进一小段这条轮廓线，转头时在脸边露出来。把这两张变体交给 See-through 拆可以去掉（第 3 步）。

Half-body Live2D Avatar Skill

English | 简体中文

Give an AI agent (such as Claude Code) one character illustration or a text description, and it builds a half-body Live2D avatar for streaming in VTube Studio, step by step. No manual modeling, no Cubism Editor, no mesh editing.

Features

• Head turns left/right and up/down (±30); the body leans when the head tilts; body follow and breathing
• Blinking and winking, eye tracking, eyebrow movement, lip sync, smiling mouth corners
• Hair physics in sections: bangs, side locks, back hair or bun; side locks and long hair swing in three sections, each a beat behind the one above; hair bounces when nodding; twin tails each swing from the hair tie; long hair follows the body below the shoulders. Bangs are optional, and the side hair can be tucked behind the ears
• Necklace pendant swings with the body; drop earrings swing from the earlobes
• Glasses follow the face
• Hotkeys: smiling eyes, O-shaped mouth, angry, troubled; wave, open hands and pointing gestures; blush

Not supported: large head turns, full body, arms following the camera continuously.

The output is a model file VTube Studio loads directly (.moc3), not a Cubism Editor project, so the Editor can't open it. For production-grade results (finer physics, more expressions), import the separated layers into Cubism Editor and rig them again. Suited to front-facing half-body characters with short hair, hair past the shoulders or twin tails.

How the illustration is adjusted

The agent redraws your illustration or description into a version that separates cleanly into layers, and you approve it before the next step. The face, hair color, eyes, clothing, palette and art style stay the same; these are adjusted:

• Framing: front-facing half body from the top of the head to the waist, plain white background; arms hang at the sides with a gap from the body, hands empty. The three gestures are edited from this pose.
• Bangs: optional. With bangs, a straight-cut fringe ending above the eyebrows, both eyebrows fully visible; where the bangs do cover an eyebrow, it shows through them, half transparent. Without, the whole forehead shows.
• Side hair: either one smooth section on each side of the face, covering the ear and ending at the chin, swinging on its own when the head turns; or tucked behind the ears, which stay visible.
• Long hair: hangs behind the neck, shoulders and back, showing only beside the neck and outside the arms; not over the shoulders, chest or arms.
• Twin tails: tied above and behind the ears, hanging behind the shoulders.
• Neck: a stretch of neck shows between the chin and the collar, so the chin slides over it when the head turns.
• Color and light: hair and skin in different colors, hair with a thin outline; flat lighting, no cast shadows. Shadows would shift out of place once the parts move.
• Accessories: glasses stay, drawn with a thin frame and clear lenses without glare; drop earrings stay, with the hair behind the ears; chokers and hanging ribbons are removed; a necklace stays only as a thin chain on the clothing with at most one pendant; hats sit on top of the head without covering the forehead or eyebrows.
• Blush: soft blush on the cheeks.

For hairstyles or accessories outside this list (animal ears, braids), ask the agent to extend the skill: add drawing rules, adjust the layer-splitting and rigging code, then check the result in VTube Studio.

What you do

1. Approve the illustration the agent generates.
2. Agree to upload it to See-through for layer separation (Hugging Face, ModelScope as backup; not needed when See-through runs on your Mac).
3. Check the avatar in VTube Studio against the checklist, then reply "pass" or "fail: what's wrong".

Requirements

• An AI agent that runs skills, such as Claude Code
• Python 3.10+, ffmpeg
• A ChatGPT account: images are generated with the Codex CLI (bundled with the ChatGPT desktop app). Another image tool that can edit images can be used instead (not yet tested on a full character)
• See-through, at least one of:
  • Hugging Face, free (preferred, a few minutes per run): create a Read token and put it in the HF_TOKEN environment variable or ~/.cache/huggingface/token. Without logging in, the daily free quota may not cover one run; logged in, about 1–2 runs a day
  • ModelScope, free (backup; queued, a run can take half an hour; higher resolution): create an access token and put it in MODELSCOPE_API_TOKEN or ~/.cache/modelscope/token
  • Or run See-through on your own Mac (optional; nothing is uploaded, no quota): tested on Apple silicon with 24 GB of memory, about 21 minutes per illustration. Setup in references/出图.md (“本机跑 See-through”)
• VTube Studio
• Live2D Cubism Core: included with Cubism Editor, or download the free Cubism SDK for Native

Tested on macOS. Not tested on Windows.

Getting started

1. Put this repository in your agent's skill folder. For Claude Code: git clone https://github.com/bellisji233/live2d-halfbody-skill ~/.claude/skills/live2d-halfbody
2. Install dependencies: pip install -r requirements.txt
3. Tell the agent "Make a VTube Studio avatar from this illustration" with the image path, or describe the character you want.

One character takes 18–22 generated images and one See-through run; from illustration to VTube Studio is about an hour, see FAQ.

FAQ

How long does one character take?

Timings from the third character (glasses):

Machine time adds up to about 30–45 minutes; with your approval and check, a character can be in VTube Studio within an hour if nothing goes wrong. The number of variants depends on whether the character has a hat or hair accessory, bangs, side hair in front of the ears, and pendants.

When the Codex or See-through quota runs out, the run stops at that step. Run it again once the quota resets; images already generated are not redone.

Language

The skill instructions (SKILL.md, references/) and script messages are in Chinese. The agent reads them as they are; talk to it in any language.

License

MIT, see LICENSE. rigkit/vendor/py-moc3 is MIT, license included. Live2D Cubism Core is not distributed with this skill; it is used under Live2D's license.