# Character Reference Sheets

Makes consistent character reference images from one anchor view, with per-view regeneration.

- Repository: https://github.com/eternityspring/shuohao-skills (5850 stars)
- Category: Design
- License: Apache-2.0
- Last updated: 2026-10-26
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add eternityspring/shuohao-skills --skill character-refs -g -a claude-code -y`
Codex: `npx skills add eternityspring/shuohao-skills --skill character-refs -g -a codex -y`
Cursor: `npx skills add eternityspring/shuohao-skills --skill character-refs -g -a cursor -y`
Gemini CLI: `npx skills add eternityspring/shuohao-skills --skill character-refs -g -a gemini-cli -y`

## Description

给任何故事里的角色真出参考图（小说改编、自己原创的故事、单独设计一个角色都行，不需要小说原文）： 一段话描述角色，拆成分层字段、补全后确认， 先出一张正面全身锚点，其余视图（大头照、90° 侧面、背面、细节、45° 大头照）都只参考这张锚点， 按需分档出图。每张图带标识、可单独重出，重出后自动标出哪些图过期。 支持 Qwen Image（ComfyUI）、codex 内置出图、OpenAI Images API（GPT Image 2）和自定义命令，主图与派生图可以使用不同模型。 产出 asset.json + 一组 PNG + 双击就能开的报告。零依赖。 只要提示词、不出图的话使用 novel-characters。 Use when asked to 出角色图、做角色参考图、给我的角色出图、定妆照、真出三视图、character reference images。

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## character-refs

输入一段角色描述，输出一组角色参考图, , **角色从哪来都行**：小说改编、自己编的故事、临时想到的一个人。**一张正面全身锚点，其余每张都只参考这张锚点**。
给视频模型（H3 / Wan / Seedance）当参考图使用，也给人看。

`{baseDir}` = 本文件所在目录。脚本 `{baseDir}/scripts/character-refs.mjs`，零依赖，`node` 直接跑。

**这是仓库里唯一真出图的 skill。**其余 skill 只交提示词，因为出图那一刻才能决定模型和画风；
这个 skill 就是「那一刻」, , 模型在 Step 0 由用户选定，画风在建角色时选择（默认动漫，另有写实预设，也能挂自定义画风）。

### 核心规则（先读懂再动手）

- **一组图只有一个根：正面全身锚点。**只有它是文生图，其余全是「锚点 + 一句改图指令」。
  头发、脸、领口三类细节额外挂确认过的正脸大头照。图与图之间不再互相参考, , 所以任何一张出坏了，单独重出这一张就行，不会连锁。
- **分档，默认出到第二档**：

  | 档位 | 内容 | 什么时候出 |
  | --- | --- | --- |
  | 1 | 正面全身（锚点） | 总是，第一张 |
  | 2（默认） | 正脸大头照、90° 侧面（面朝画面右侧）、背面 | 默认就出齐 |
  | 3 | 细节图（最多 8 张）：用户点名的、角色最能认出来的地方；没有就用默认的头发 / 发饰、领口、袖口、鞋 | 有配饰或服装局部的特写 |
  | 4（默认不出） | 45° 大头照（面朝画面左侧） | 用户明确要 |

  H3 实测：只给正面全身，服装和背影都对，但脸会走样；**加一张大头照，脸最接近**。所以默认出齐第二档。
  只要锚点（比如先看看长相再说）：`gen <asset.json> --tier 1`。
- **模型不锁定**：主图与派生图可以使用不同模型，重出单张也可以换模型。一致性来自「同一张锚点」，
  不来自「同一个模型」（实测 Qwen 锚点 + GPT 派生、GPT 锚点 + Qwen 派生、同组混用都衔接得上）。
  每张图记录自己的模型，同组混用只在报告里提醒。
- **冻结的只有三样**：锚点文件（sha256）、画风快照、文字描述指纹。任何一样变了，
  依赖它的图标成「过期」, , **只标记，不删除**，旧版本全部留着。

---

### Step 0, 初次设置（每台机器一次）

```bash
node {baseDir}/scripts/character-refs.mjs config --show
```

输出末尾写「还缺：……」就要问用户这三件事，**一次问完**：

1. **主图（锚点）使用哪个模型**：
   - `qwen`, , Qwen Image 2.1，走自己的 ComfyUI 服务器。快（每张 25, 45 秒）、尺寸精确、不吃订阅额度。
     需要 `COMFY_URL`（可选 `COMFY_USER` / `COMFY_PASS`），放环境变量或一个 .env 文件
   - `codex`, , codex 内置出图（GPT）。不要 API key，但**吃 ChatGPT 订阅额度**（Plus 约 25 张会触顶，几小时后恢复），每张 80, 160 秒
   - `openai`, , OpenAI Images API，默认 `gpt-image-2`。按量计费，要 `OPENAI_API_KEY`；也能指到兼容接口（`--openai-base-url`）
   - `custom:<名字>`, , 用户自己的出图命令，见 `references/models.md`
2. **派生图使用哪个模型**：默认与主图相同。可以分开（比如锚点 GPT、派生 Qwen）
3. **出完锚点要不要停下来等人确认**：推荐 `yes`, , 锚点是全组的根，它不对后面全白出。
   选 `no` 则自动放行，报告里标「未经人工确认」；**没过检查门的锚点不会自动放行**，要人看过再 `confirm` 或重出

```bash
node {baseDir}/scripts/character-refs.mjs config --model qwen --confirm-anchor yes --qwen-env-file <.env 路径>
# 分开设置：--anchor-model codex --derive-model qwen
```

The rest: https://github.com/eternityspring/shuohao-skills/blob/HEAD/skills/character-refs/SKILL.md