前置条件很少，README 用一张表说清了必需与可选的边界。开工前对着这四条自查一遍，能省掉后面大半的排查。

1. Node ≥ 18——必需。skill 的脚本只用标准库，没有 npm 依赖，不需要 install，clone 完就能跑。
2. 一个 AI 编码 agent——必需。Claude Code 或 codex 都行，模型额度走当前会话，官方明确说「不需要任何 API key」。
3. codex CLI（可选）——只有出图才用得上，走内置 $imagegen。没有就跳过出图环节，角色、美术、分镜的文字与 JSON 产出照常生成。
4. 一本够长的小说——整条管线从小说开始。官方端到端 demo 用的是《渡口》，工作目录不放在仓库里，仓库只固化归档约定。

安装只做一件事：把仓库 skills/ 下的目录软链到本机 agent 的技能目录。所谓「自动检测」，是脚本看你装了 Claude Code 还是 codex，然后往对应的 ~/.claude/skills 或 ~/.codex/skills 建链接。

git clone https://github.com/eternityspring/shuohao-skills.git
cd shuohao-skills
./scripts/install.sh

./scripts/install.sh novel-characters   # 只装某一个
./scripts/install.sh --codex            # 只装到 codex
./scripts/install.sh --uninstall        # 取消软链

ln -s "$PWD/skills/novel-characters" ~/.claude/skills/novel-characters
ln -s "$PWD/skills/novel-characters" ~/.codex/skills/novel-characters

五个 skill 各管一道工序，每个都会产出 json / md / html 三件套。可以按顺序整条跑完，也可以只用其中一段。

五个 skill 的报告界面都支持中英双语：默认中文，render --lang en 出一份全英文报告，而数据内容（人名、台词、提示词）保持原文不动。这意味着同一套产物可以直接对外交付。

这个仓库真正值得抄的不是五个 skill 的模板，而是压在它们下面的两条纪律。它们决定了产出能不能被信任。

第一条：质量门交给脚本，不交给模型。「爽点表不能为空」「分镜必须落在 2–5 秒」「钩子要在前 3 拍兑现」这类判据，如果用自然语言写在 prompt 里，模型会忘、会自我宽恕、会在长上下文里前后不一致。shuohao-skills 把它们全部下沉成 .mjs 确定性检查：大纲 14 道、美术 11 道、剧本 10 道、分镜 17 道，跑一次几秒，不花额度，同样的输入必然给同样的结论。更严的是仓库级的第二条硬要求——每个 skill 必须自带 scripts/selftest.mjs，不调用模型、不花额度，覆盖全部确定性逻辑。等于说 skill 自己也被上了门。

第二条：分镜只做输出，不做新决定。结构在大纲阶段收敛，剧本、场景、角色三者同步迭代，等流程走到分镜，所有创作上的选择其实已经做完了。分镜的职责只剩翻译：把已经定下的东西切成生成模型能吃的单元——段的长度上限、每个切点的时刻、拿哪张设定图当参考、H3 提示词里的对齐指令。所以它才会去跟提示词做「逐字对账」，而不是再创作一次。这条纪律挡住的是一类很难查的问题：下游模型在分镜阶段悄悄改了构图或剧情，导致同一角色在不同镜头里长得不一样。

* 质量门数量与职责定位均来自官方 README；角色设定集一栏未单独披露门数，故留空而非估算。

五段各出一份 HTML 报告，交付时来回翻很碎。仓库带了一个组装脚本，把它们并成一张左侧导航切换的单页。

node scripts/report.mjs --from <demo目录> --out report.html

--from 会按仓库的目录约定自动发现五份 json；也可以逐个指定 --outline、--cast、--art、--script、--storyboard。有哪几段就出几个面板——只跑了角色那一段，就只有一个面板，不报错。

它对自己的定位写得很克制：是组装器，不是独立 skill。不 import 任何 skill 的代码，而是调各自的 render --html 拿产物再拼装。所以五个 skill 一行都不用改，各自仍然能独立跑、可以单独拷走；哪天某个 skill 改了渲染，这边自动跟上。

合并这件事听着简单，它得解决三个具体问题，而且三件都放在组装器里做，不侵入 skill：

• 样式串味——五份报告共用 57 个类名，其中 13 个同名不同定义，比如 .copy、.kpis、.badge、.chip。做法是给每份样式的每条选择器加一个作用域前缀。
• 脚本串味——各报告的脚本写的都是 document.querySelector('.expo') 这类全局查询，合成一页后只会命中第一个，五个导出按钮会全废。做法是给每份脚本套一层作用域代理。
• 图片路径——每份报告里的图相对自己那份 json 的目录，像 images/…、E01-01/f1.png，合成后要按输出文件的位置重算一遍。

交互也做了取舍：默认一次只显示一个面板（五份加起来将近六十万字符，全展开浏览器会很吃力）。左下角有「平铺全部」把所有面板同时展开，数字键 1–5 切面板，#pane-script 这样的深链可以直接分享到某一屏，Cmd+F 恢复全局搜索。

node scripts/report-selftest.mjs   # 92 项断言

仓库没配 CI，理由很实在：自测足够快，本地跑一次比等 CI 更省事。所以验收就靠下面两条自测命令加两条归档约定。

1. 跑全部自测——加新 skill 之前先把所有自测过一遍，一秒内跑完，不调模型。
2. 跑组装器自测——node scripts/report-selftest.mjs，92 项断言，不起浏览器。
3. 按五个目录归档——产物别平铺在根目录，按 outline/、characters/、art/、script/、storyboard/ 各建一个目录，一眼对应流水线五段。
4. 控制提交范围——报告 HTML 和生成的图、视频都能靠 render 重跑再生，建议只提交 json / md / docs / scripts，把 HTML 和分镜 PNG 用 .gitignore 排除，保持仓库轻量。

for f in skills/*/scripts/selftest.mjs; do node "$f"; done