企业官网建设流程全解析

打开 GitHub 看到“小黑插图 Skill”这个项目挂到 11.7k star 的时候，我第一反应是：这又是一个绑死在 Codex 生态里的玩具。直到我把它里面的指令文件、参考图资源和提示词模板搬到 Claude Code，真的跑出一张像模像样的小黑插画，我才意识到，这种“Skill 平替”的折腾过程，其实是很多 AI 工具使用者都会遇到的一次典型迁移实战。

这篇文章不打算讲空洞的概念，直接从项目是什么、为什么只能在 Codex 里用、怎么改成 Claude Code 能识别的 Skill、迁移之后有哪些坑，一条线讲完。适合两类人：一类是已经在用 Codex、想保留一套好用插图技能包的开发者；另一类是主力工具是 Claude Code、看到别人分享的 Skill 却不知道如何换成自己能用的读者。读完你至少能自己动手把一个 Codex 生态的 Skill 改造成 Claude Code 版本，顺便搞清楚这两个工具在“给 Agent 定义技能”这件事上的底层差异。

1. 小黑插图 Skill 到底是什么，为什么它值得折腾

1.1 一个 11.7k star 的 Skill 通常解决什么问题

小黑插图 Skill 说白了，是一套给 AI 编程代理用的“插图生成技能包”。它把一个叫“小黑”的虚拟 IP 角色形象设定、常用场景、构图模板和配色规则，整理成一套结构化的指令文件，还附带了一批参考图资源。使用的时候，你只要告诉 Agent 想要什么场景，比如“小黑在阳台看书”，Skill 就会按照统一风格输出一张插图，可能是 SVG，也可能是 PNG，而不是每次都靠模型自由发挥。

这套思路解决的是 AI 画图里最让人头疼的“风格漂移”问题。很多人用 AI 画过配图都有这个体验：同一句话、同一个模型，上午画出来是一个样子，下午再画就换了发型、换了配色，甚至人物比例都变了。小黑插图 Skill 的做法，就是把角色外观和画面规则写成明确的文字约束，再配合参考图，把模型的发挥空间收窄到一个可控范围内。你可以把它理解成给 Agent 发了一本带图例的《人物设定集和分镜手册》，它每次工作前先翻手册，再动手画。

这个项目能拿到 11.7k star，我观察下来有三个原因。第一，它不挑具体画风，默认的扁平插画风格很适合做技术文档配图、PPT 插图和社交媒体的封面图；第二，它的使用门槛很低，不需要复杂的训练和模型微调，只要你用的 Agent 支持自定义指令，就能拖进去用；第三，作者把角色设定、场景模板和渲染脚本都开源了，大家不光能用，还能改成自己的版本。说白了，它是把“给 AI 立人设、定画风”这件事产品化了，自然容易传播。

1.2 为什么“Codex 专属”会成为门槛

听起来这么好的东西，为什么不能直接在 Claude Code 里用？这就要说到工具链的封闭性了。小黑插图 Skill 最初是按 Codex 的使用习惯组织的：在项目目录里放一个AGENTS.md，在用户目录下放一组prompts/*.md文件，用户通过斜杠命令手动触发。Codex CLI 每次启动都会读取这些文件，把里面的指示当成系统上下文的一部分，所以运行起来非常自然。

但 Claude Code 不认识这套组织方式。它读取的是.claude/skills/<名字>/SKILL.md，而且触发逻辑也不一样，不是用户输命令才加载，而是模型根据对话内容判断“该不该加载”。这就导致一个尴尬局面：哪怕你把整个小黑插图 Skill 的仓库克隆下来，放到任何一个 Claude Code 项目里，模型也只会把它当成普通文档，根本不会主动按照里面的规则去画图。你需要先做一次“翻译”，把 Codex 的指令格式改成 Claude Code 的 Skill 格式，同时把触发方式从“手动”改成“自动+手动兼容”。

这个门槛不在于代码有多难，而在于很多人没有意识到两个工具对“技能”的定义不是一回事。后面这两章，我会先把两边机制的关键差异讲清楚，再给出具体迁移步骤。

2. Codex 与 Claude Code 的 Skill 机制差异，决定你该怎么平替

2.1 Codex 侧：指令文件与自定义 Prompt 的加载方式

Codex 这边的工作方式比较像早期的命令行工具。它会在项目根目录读取AGENTS.md，这个文件相当于项目说明书，里面写了“项目里有什么、模型应该注意什么、有哪些约定”。除了这种每次自动加载的说明文件，Codex 还支持把一组自定义 Prompt 放到~/.codex/prompts/目录下。比如你可以建一个illustration.md，里面写好小黑插图的角色设定和输出要求，然后在对话里输入/illustration 小黑在阳台看书，Codex 就会把illustration.md的内容和你的输入拼在一起，作为一次完整的生成请求。

这种模式的好处是简单、透明、可控。用户明确知道自己调用了哪个技能，Prompt 文件的逻辑也很直白，想改哪里就直接改文本。但缺点同样明显：如果使用者不知道有illustration.md这个命令，就不会去用；如果项目换了一台机器，~/.codex/prompts/目录没有同步，技能就丢了。小黑插图 Skill 在 Codex 里之所以好用，很大程度上依赖这种“手动触发”带来的确定感。

另外 Codex 的 Prompt 文件里经常使用变量，比如$SCENE、$MOOD。这些变量由调用者传入，由工具在运行时替换成具体的场景描述。这种模板化写法在纯手动触发场景下非常高效，但也给后续迁移埋了坑，因为 Claude Code 的 Skill 机制里并没有模板变量的概念。

2.2 Claude Code 侧：SKILL.md 与 skills 目录的规范

Claude Code 这边用的是 Agent Skills 机制，结构上要比 Codex 的 Prompt 文件更规范一些。一个技能是一个目录，目录名就是技能名，里面必须有一个SKILL.md文件作为入口。SKILL.md的开头需要写一段 YAML 格式的 frontmatter，至少要包含name和description两个字段。description特别重要，因为模型就是靠读这段描述来决定“用户的需求跟这个技能匹不匹配”。如果 description 写得太宽泛，模型会在不需要的时候误加载；写得太窄，又可能永远触发不了。

SKILL.md的正文部分就是实际指令。这里可以写具体的操作步骤、输出格式、注意事项，也可以用相对路径引用同目录下的参考图和模板文件。Claude Code 的加载逻辑是：模型在对话过程中觉得“这个问题适合用某个技能”，就会自动读取对应目录里的SKILL.md和附属资源。当然，用户也可以直接说“使用 xxx 技能”，强行让模型加载。

项目级技能放在.claude/skills/<skill-name>/，全局技能放在~/.claude/skills/。项目级的好处是跟着仓库走，团队协作时每个人拉下来就能用；全局的好处是任何项目都能用。我建议迁移阶段先用项目级，方便测试和版本管理。

2.3 两种机制的映射关系，别只当格式转换

把两边放一起对比，会看得更清楚：

这里我要强调一点：平替不是简单地把文件后缀从.md改成SKILL.md，更不是写个脚本批量转换就能完事。Codex 的 Prompt 文件是“用户主动查询的手册”，Claude Code 的 Skill 是“模型根据上下文自主调用的能力包”。这两种心智模型完全不同。如果不改触发描述、不改资源引用方式，迁移过去的东西只是一个能看不能用的僵尸文件。

3. 手把手：把小黑插图 Skill 迁移到 Claude Code

3.1 准备目录结构，一个萝卜一个坑

我先给出一个我实际用着顺手的目录结构，你可以直接抄：

.claude/skills/xiaohei-illustration/ ├── SKILL.md ├── assets/ │ ├── xiaohei-character.png │ ├── style-reference.png │ └── palette.png ├── templates/ │ ├── scene-study.md │ ├── scene-work.md │ ├── scene-life.md │ └── scene-festival.md ├── scripts/ │ └── render_svg.py └── output/

每个目录都有它的作用。assets/放角色参考图和风格参考图，这些图是模型生成时必须看的“质量标准”；templates/按场景分类放提示词模板，避免每一次都把全部规则塞给模型；scripts/放渲染脚本，用来把模型生成的 SVG 描述落地成真实文件；output/存生成结果。

有一个细节要注意：Claude Code 加载技能时，会把SKILL.md所在目录当成根目录。所以SKILL.md里引用资源，一定要用相对路径，比如assets/xiaohei-character.png，不要写./.claude/skills/xiaohei-illustration/assets/...这种绝对路径。绝对路径在你自己机器上可能能用，换个环境就全废了。

3.2 编写 SKILL.md，把“怎么画”变成“怎么想”

SKILL.md是整个迁移的核心。下面是简化后的示例，我已经按我的使用经验调整过措辞：

--- name: xiaohei-illustration description: 当用户需要生成小黑IP风格的插画、配图、四格漫画、文章封面图或示意图时使用。适合响应包含“小黑插图”“小黑风格”“小黑配图”“画一张小黑”等关键词的请求，也适合用户描述某个生活或工作场景并要求配图的情况。 --- # 小黑插图 Skill ## 任务目标 根据用户的场景描述，生成一张符合“小黑”角色设定的插图。输出优先使用 SVG 格式，必要时转换为 PNG。 ## 开始前必做 1. 先读取 `assets/xiaohei-character.png`，记住角色关键特征：黑色短发、圆脸、日常休闲装。 2. 读取 `assets/style-reference.png`，确定整体风格：扁平插画、简洁线条、低饱和配色。 3. 如果用户没有指定场景类型，从 `templates/` 中选择最接近的一个模板。 ## 生成步骤 1. 提取用户描述中的核心场景，包括人物动作、环境、光线、情绪。 2. 对照 `templates/` 中对应模板，补全“背景元素”“配色倾向”“构图建议”三个字段。 3. 在生成画面之前，先在回复中列出一段“画面描述”，包含：角色动作、画面构图、主色调、背景元素。 4. 调用 `scripts/render_svg.py` 生成实际 SVG 文件，保存到 `output/`。 5. 回复中附上生成文件的相对路径。 ## 输出规范 - 角色形象必须与参考图保持一致，不要改变发型、脸型、服装主色。 - 画面默认尺寸为 1200x900。 - SVG 中不允许出现外链图片，所有元素都内联绘制。 - 如果用户需求不明确，先复述理解再动手，不要自己猜。

写这份文件时，我踩过一个坑：description 里只写了“小黑插图”，结果我输入“帮我画一张周末在阳台看书的配图”时，模型没有自动加载技能。后来我把 description 改成“也适合用户描述某个生活或工作场景并要求配图的情况”，触发率就明显上来了。所以说 description 不是写给搜索引擎看的，是写给模型的“决策依据”。

3.3 搬运参考图与提示词模板，把变量改成自然语言

Codex 版的提示词模板通常长这样：

场景：$SCENE 角色动作：$ACTION 光线：$LIGHT 情绪：$MOOD 风格：flat_illustration

这种写法在 Codex 里没问题，因为调用时会做变量替换。但 Claude Code 的 Skill 不认这玩意儿，模型只会把这四行当成固定文本读一遍，根本不知道$SCENE是什么。所以迁移时要改成自然语言指令，比如下面这样：

# 学习场景模板 适用场景：读书、写作业、上课、复习、考试准备。 当你确定用户描述的是学习场景后，按以下方式组织画面： - 角色动作：用户描述中提到的动作，默认是拿着书或坐在书桌前。 - 背景元素：书架、台灯、水杯、窗外的树，按需选择。 - 光线方向：优先从画面左侧打入暖光。 - 配色倾向：主色调采用暖黄和灰白，点缀色用深蓝。 - 构图建议：人物放在画面中线偏右，留出左侧背景空间。

改造的核心原则是：不要指望模板引擎帮你填变量，而是让模型自己根据用户描述去“填空”。模板的价值在于限定思考框架，而不是替你完成拼接。我保留了 4 个场景模板，再多就费上下文了。模板不是越多越好，模型每次加载技能时都会把模板内容算进上下文里，模板太多会挤占真正画图的容量，还容易让模型抓不住重点。

3.4 在项目里启用并验证，别急着写代码

迁移完成后的第一件事，不是急着跑脚本，而是先验证技能能不能被正确加载。进入项目目录后，直接启动claude，然后问一句“你会用什么方式帮我生成一张插图”。如果模型提到要读取某个 Skill，说明自动触发链路通了。

如果没提，也不要慌，先在输入里点名“使用 xiaohei-illustration skill”，手动加载成功后，再反推 description 哪里写得不够准。我个人习惯在正式使用前做三轮测试：第一轮手动触发，确认指令本身没问题；第二轮描述一个不带关键词的场景，看自动触发是否生效；第三轮跑完整流程，确认能在output/下生成真实文件，而不是只给一段 Markdown 图片链接。三轮全过，才叫迁移成功。

这里还要提醒一个容易被忽略的点：如果你给项目配置过claude_desktop_config.json或者用了别的项目管理工具，改了.claude/skills/之后一定要重启会话。很多“技能不生效”的问题，其实是旧会话还留着旧的上下文，模型根本没有重新去扫目录。

4. 实操过程与效果验证：同一幅插图的生成对比

4.1 用 Codex 生成示例，先摸清原始的产物特征

我在迁移前用 Codex 跑过一组基线测试，输入是“小黑周末在阳台看书，午后阳光，画面安静”。Codex 加载了原来的illustration.md之后，输出分成三段：第一段是画面描述，第二段是构图拆解，第三段是 SVG 代码。我印象比较深的是它的构图拆解写得很规矩，会把“前景人物、中景阳台栏杆、背景绿植和光影”分层说明，然后 SVG 里也确实是按这个层次画的。

Codex 原版的产物特征有几个：线条简洁、主色调偏灰白加暖黄、人物比例偏 Q 版、脸部只做简化处理。缺点也很明显，一旦场景描述变长，比如加了一句“旁边有一杯冒热气的咖啡”，它有时会因为上下文长度问题漏掉部分背景元素，需要在 SVG 里手工补。另外它的输出高度依赖用户手动触发，换一个人用同一套 Prompt，可能根本不知道有/illustration这个命令。

4.2 用 Claude Code 加载后的输出差异，问题出在哪里

迁移到 Claude Code 后，我用同样一句话测试：“画一张小黑周末在阳台看书的插图，午后阳光，画面安静。”第一次测试时，模型完全没有自动加载技能，因为我的 description 写得太具体，只写了“小黑插图”“小黑风格”，而我的输入里没有这些词。改成 3.2 里的那段 description 之后，第二次测试自动触发了。

但触发之后又暴露了另一个问题：模型没有先读assets/xiaohei-character.png，而是凭自己对“小黑”这个名字的理解画了一张图，脸的轮廓明显偏尖，跟我参考图里的圆脸设定对不上。这个问题的根源在于 SKILL.md 里虽然写了“开始前必读”，但权重不够。我改成“开始任务前，必须先描述 assets/xiaohei-character.png 中角色的关键特征，再继续生成”之后，模型每次都会先输出一段“角色特征：黑色短发、圆脸、休闲装”，然后才进入构图阶段，角色还原度明显提高。

4.3 如何判断迁移成功，列一份客观检查清单

很多人在这一步只凭“眼睛看着像不像”来判断，容易自我感觉良好。我建议用下面这张检查清单，逐项打勾：

如果这六项都能过，那这个平替基本算成功了。如果过不了，问题一般不是出在“画得不好看”，而是出在机制层面，请直接看下一章的排查列表。

5. 常见问题与排查技巧实录

5.1 SKILL.md 没有被识别，先查这三处

这是出现频率最高的问题。第一处是目录层级，很多人把文件放成了.claude/skills/SKILL.md，少建了一个技能名字目录。正确结构必须是.claude/skills/xiaohei-illustration/SKILL.md，Claude Code 靠目录名识别技能。第二处是 frontmatter 格式，name字段里不能有空格，也不能用中文名；description必须存在，否则整个文件不会被当成合法技能。第三处是文件扩展名，必须是.md，别存成.markdown或.txt。

改了这些之后，记得重启会话，因为技能的扫描发生在会话启动阶段，不是对话过程中实时扫描。

5.2 提示词模板里的变量不生效，原来是机制不同

这个问题我在 3.3 里已经提到，但值得单独拎出来说。从 Codex 迁移过来的老手最容易踩这个坑：看到模板里有$VAR，下意识觉得只要替换成具体内容就能用。实际上 Claude Code 不提供模板渲染层，SKILL.md 里所有内容都是直接喂给模型的文本。变量不生效，模型也完全可能忽略掉“变量”这个概念。

解决办法只有一个：把变量改写成自然语言指令。比如把$SCENE改成“从用户描述中提取场景关键词，并展开为具体的环境细节”；把$ACTION改成“判断人物动作，如果用户没有明确说明，默认选择模板中的推荐动作”。改完之后你会发现，模板虽然看起来啰嗦了一点，但模型的执行稳定性反而更高了。

5.3 生成图片时只有链接没有文件，要用脚本兜底

迁移初期我遇到过一种很迷惑的情况：模型在回复里输出了一段像模像样的 Markdown 图片链接，但output/目录里根本没有对应文件。这是因为模型在文字回复中“模拟”了图片生成流程，实际并没有执行任何文件写入操作。要根治这个问题，必须把“生成文件”变成 Skill 里强制执行的步骤，而不是“可选输出”。

我通常会在 SKILL.md 里写死：必须调用scripts/render_svg.py，并把生成路径写到回复里。下面是一个简化版的脚本，负责把模型输出的 SVG 描述转成真实文件：

#!/usr/bin/env python3 import re import sys from pathlib import Path def extract_svg(text: str) -> str: match = re.search(r"<svg.*?</svg>", text, re.S) return match.group(0) if match else "" def main(): source = sys.stdin.read() if not sys.argv[1:] else Path(sys.argv[1]).read_text() svg = extract_svg(source) if not svg: print("NO_SVG_FOUND") return out_dir = Path(__file__).parent.parent / "output" out_dir.mkdir(exist_ok=True) out_file = out_dir / "xiaohei_latest.svg" out_file.write_text(svg) print(f"SAVED:{out_file}") if __name__ == "__main__": main()

这个脚本很粗糙，但足够说明思路：模型输出 SVG 代码片段，脚本用正则提取，写入文件。真正生产环境可以再加参数校验、尺寸转换和 PNG 导出，但核心逻辑就是这样。

5.4 迁移后启动报错，provider 与 endpoint 配置冲突

还有一个不算常见但一旦遇到就很浪费时间的问题：从 Codex 切到 Claude Code 时，有人会把 Codex 的配置文件一起复制过来，结果启动时报类似“endpoint 处理失败”的错误。这里的关键是，两个工具的 API 接入配置字段并不通用，尤其是一些自定义 provider 和 endpoint 的配置段，复制过去不仅没用，还会让 Claude Code 在初始化时读到一堆它不认识的字段。

处理方式很直接：把 Claude Code 的配置恢复成官方默认格式，只保留模型名称、身份验证相关必要字段，剩下跟工具链绑定的字段全部删掉。不要照搬跨工具的配置段，也尽量不要从某个“通用配置生成器”里一把梭复制，那种工具往往把多个平台的配置逻辑揉在一起，反而制造冲突。按官方文档重新初始化一次，比花半小时排查字段冲突要划算得多。

5.5 资源文件太大拖慢速度，用压缩预览图解决

最后分享一个经验。小黑插图的参考图如果都是高清 PNG，每张可能一两 MB，模型每次加载技能都要把这些图读进上下文，速度会被拖慢，而且 token 开销也大。我后来在assets/里额外放了一组preview/缩略图，SKILL.md 里明确写“优先读取 preview 下的压缩图，assets 下的原图仅在需要查看细节时使用”。实测下来，加载速度提升明显，角色特征保留得也足够。

如果你发现自己配了好几个 Skill，模型还会出现互相干扰的情况，比如画图的时候加载了写文案的技能。这时候请回头检查每个 Skill 的 description，让每个技能只描述自己最擅长的任务，不要写“如果用户需要插图或文案都可以用我”这种大杂烩描述。

整套平替跑下来，我最大的感受是：一个 11.7k star 的 Skill，真正值钱的不是那几段提示词，而是角色设定、资源文件和使用场景之间的耦合关系。迁移的时候，别只想着改文件后缀，要把“触发方式、上下文依赖、输出路径”这三件事重新对一遍。后面我打算把这次迁移整理成一个通用模板，顺便补一组适合英文环境的 Prompt 版本，有需要的话也可以把小黑插图 Skill 适配到其他支持自定义指令的 Agent 上，思路是一样的，只是外壳不同。