打开 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 两种机制的映射关系别只当格式转换把两边放一起对比会看得更清楚维度CodexClaude Code技能载体~/.codex/prompts/*.mdAGENTS.md.claude/skills/name/SKILL.md触发方式用户手动输入斜杠命令模型根据 description 自动触发也可手动要求资源引用通常用仓库内的相对路径相对 SKILL.md 所在目录模板变量支持$VAR式变量替换不支持模板变量需要用自然语言指令指令层级项目级与全局级并存项目级与全局级并存项目级优先典型使用场景命令行手动调用的工具链自动判断、多技能共存的 Agent 工作流这里我要强调一点平替不是简单地把文件后缀从.md改成SKILL.md更不是写个脚本批量转换就能完事。Codex 的 Prompt 文件是“用户主动查询的手册”Claude Code 的 Skill 是“模型根据上下文自主调用的能力包”。这两种心智模型完全不同。如果不改触发描述、不改资源引用方式迁移过去的东西只是一个能看不能用的僵尸文件。3. 手把手把小黑插图 Skill 迁移到 Claude Code3.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 如何判断迁移成功列一份客观检查清单很多人在这一步只凭“眼睛看着像不像”来判断容易自我感觉良好。我建议用下面这张检查清单逐项打勾检查项通过标准自动触发输入“画一张周末看书的配图”不需要手动提技能名模型主动加载该 Skill角色一致性输出图中角色为黑色短发、圆脸、休闲装与参考图一致资源引用SKILL.md 和输出内容均使用相对路径没有外链图片结构完整输出包含角色动作、背景元素、配色倾向、构图建议四要素可落地在output/下能找到实际生成的 SVG 或 PNG 文件不是一段假链接可重复同一句话连续跑两次角色和配色风格基本稳定如果这六项都能过那这个平替基本算成功了。如果过不了问题一般不是出在“画得不好看”而是出在机制层面请直接看下一章的排查列表。5. 常见问题与排查技巧实录5.1 SKILL.md 没有被识别先查这三处这是出现频率最高的问题。第一处是目录层级很多人把文件放成了.claude/skills/SKILL.md少建了一个技能名字目录。正确结构必须是.claude/skills/xiaohei-illustration/SKILL.mdClaude 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(rsvg.*?/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_okTrue) out_file out_dir / xiaohei_latest.svg out_file.write_text(svg) print(fSAVED:{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 上思路是一样的只是外壳不同。