1. 从 11.7k star 的专属能力说起为什么我要做这个平替第一次在 Codex 里用上那个插图 Skill 的时候我盯着终端里一行行滚出来的 SVG 代码心里就一个念头这东西要是 Claude Code 也能用就好了。那个项目在 GitHub 上攒了 11.7k star核心能力其实很朴素——你给它一段文字描述它帮你生成一张干净的插图输出格式是 SVG。不是那种糊成一团的位图是矢量图放大缩小都不失真扔进文档、PPT、网页里都体面。但问题也很明显它是 Codex 专属的。Codex 的 Skill 机制、调用约定、文件组织方式跟 Claude Code 完全是两套东西。你在 Codex 里跑得好好的 Skill搬到 Claude Code 里要么找不到入口要么参数对不上要么干脆报错。我身边不少朋友是 Claude Code 的重度用户看到那个插图 Skill 的效果眼馋得不行但又不愿意为了一个插图功能切回 Codex于是就来问我有没有办法在 Claude Code 里复刻一个这就是这个项目的起点。我要做的事情很明确把那个 11.7k star 的 Codex 专属插图 Skill拆解清楚它的核心逻辑然后在 Claude Code 的 Skill 体系里重新实现一遍做一个能用的平替。关键词里提到的 image_gen、SVG、Skill、Codex、Claude Code基本就是这个项目的全部技术坐标。先说清楚这个平替能做什么。你给 Claude Code 一段自然语言描述比如画一只鹈鹕骑自行车它会生成一段完整的 SVG 代码你可以直接保存成 .svg 文件或者嵌进 HTML 里预览。它不依赖任何外部图片生成 API纯靠模型对 SVG 语法的理解和空间想象能力来画。这意味着它没有网络请求、没有额度限制、没有隐私顾虑本地跑完就完事。适合谁来参考三类人。第一类是在用 Claude Code、想要一个轻量插图能力的开发者第二类是对 Agent Skill 机制感兴趣、想自己写 Skill 的人第三类是单纯想搞明白一个 Skill 到底是怎么运转的的技术爱好者。哪怕你之前没写过 Skill跟着走一遍也能上手。我踩过的第一个坑就是一开始我以为直接把 Codex 的 Skill 文件复制过来改改路径就行。结果发现两边的 Skill 定义格式、触发方式、上下文注入机制都不一样硬搬只会得到一堆无效配置。所以这个项目的核心不是搬运而是翻译——把 Codex Skill 的设计意图用 Claude Code 能理解的方式重新表达出来。2. 拆解原版 Skill 的设计思路它到底强在哪2.1 一个插图 Skill 的核心构成要复刻先得看懂原版。我把那个 11.7k star 的项目翻来覆去看了好几遍它的 Skill 结构其实不复杂核心就三块触发描述、生成指令、输出约定。触发描述决定了模型什么时候该调用这个 Skill。原版写得很克制大意是当用户需要生成插图、示意图、图标且希望得到矢量格式时使用。这句话看着简单但它把边界划得很清楚——不是所有画图需求都接只接矢量插图这一类。这一点很关键因为 Skill 的触发描述写得太宽模型会到处乱调用写得太窄又永远触发不了。生成指令是灵魂。原版没有让模型随便画而是给了一套结构化的约束先确定画布尺寸再规划构图层次然后逐层生成 SVG 元素最后做一次语法自检。这套流程把画图这个模糊任务拆成了模型能稳定执行的步骤。我实测下来有没有这套约束输出质量差距是肉眼可见的——没有约束时模型经常画出元素重叠、坐标越界、标签未闭合的残次品。输出约定则规定了结果的呈现方式必须是完整的svg标签包裹必须带viewBox必须用语义化的分组g组织元素。这些约定保证了生成的 SVG 是可用的而不是能看但没法用的。2.2 为什么选 SVG 而不是位图这里得解释一个关键选型。关键词里有 image_gen也有 SVG为什么这个 Skill 走的是 SVG 路线而不是调用图片生成模型原因有三层。第一层是可控性。位图生成是抽卡你给同样的提示词每次出来的东西都不一样而且很难精确控制某个元素的位置和颜色。SVG 是代码代码是可以被审查、被修改、被版本管理的。你生成的鹈鹕位置偏了直接改坐标就行不用重新抽卡。第二层是体积与清晰度。一张像样的位图插图动辄几百 KB 到几 MB而同样内容的 SVG 往往只有几 KB而且无限放大不失真。对于文档、网页、演示文稿这些场景SVG 是压倒性的优势。第三层是无依赖。调用图片生成 API 意味着网络请求、密钥管理、额度消耗、内容审核。SVG 生成完全在模型内部完成零外部依赖。这也是为什么这个平替能在 Claude Code 里跑得这么轻——它本质上就是让模型写一段结构化的代码。提示SVG 路线不是万能的。它擅长图标、示意图、扁平化插画、几何图形组合不擅长写实照片、复杂光影、细腻纹理。选型时要认清边界别拿它去画油画。2.3 Codex Skill 与 Claude Code Skill 的机制差异这是整个项目最硬核的部分也是最多人卡住的地方。两边的 Skill 机制表面看都是给模型扩展能力但底层逻辑差别不小。Codex 的 Skill 更偏向工具调用范式。它把 Skill 定义成一个可被调用的函数有明确的入参和出参模型在需要时发起调用拿到结果后继续。这种范式的好处是边界清晰坏处是灵活性受限——Skill 能做的事情被它的接口定义框死了。Claude Code 的 Skill 更偏向指令注入范式。它把 Skill 当成一段可被加载的上下文当触发条件满足时这段指令被注入到模型的思考过程中模型按照指令的引导去完成任务。这种范式的好处是灵活模型可以自由发挥坏处是稳定性依赖指令质量指令写得含糊输出就飘。理解了这个差异复刻的思路就清晰了我不能照搬 Codex 的函数式定义而要把原版 Skill 的意图翻译成一段高质量的指令文本让 Claude Code 在触发时加载它。换句话说Codex 版是给模型一个工具Claude Code 版是给模型一套心法。3. 动手实现Claude Code 版插图 Skill 的完整搭建3.1 环境准备与目录结构先把地基打好。Claude Code 的 Skill 通常放在项目的特定目录下我习惯在项目根目录建一个.claude/skills/文件夹每个 Skill 一个子目录。这个插图 Skill 我叫它svg-illustrator目录结构长这样.claude/ skills/ svg-illustrator/ SKILL.md examples/ pelican-bicycle.svg simple-icon.svgSKILL.md是核心文件里面写触发描述和生成指令。examples/放几个参考样例这个不是必须的但我强烈建议放——模型在生成时如果能参考已有样例的风格输出会稳定很多。这就像给新员工看几份过往的优秀作品比纯口头描述管用。关于 Claude Code 的安装如果你还没装常规做法是通过包管理器全局安装然后在项目里初始化配置。具体命令各平台略有差异核心是确保claude命令能在终端里直接调用。装完之后进到项目目录Claude Code 会自动识别.claude/skills/下的 Skill 定义。注意Skill 目录的路径和命名要严格遵循 Claude Code 的约定路径写错的话 Skill 根本不会被加载而且不会有明显报错很容易让人以为是指令写错了白白排查半天。3.2 SKILL.md 的触发描述怎么写触发描述是 Skill 的门卫决定了它什么时候被唤醒。我反复调整过好几版最后定下来的写法是这样的--- name: svg-illustrator description: 当用户需要生成矢量插图、示意图、图标、扁平化插画且期望输出 SVG 格式时使用。适用于画一个...生成一张...的图做个...图标等请求。不适用于照片级写实图像、复杂光影渲染。 ---这里有几个细节值得说。name用英文短横线命名保持和目录名一致避免混乱。description里我特意加了不适用于的排除项这是从踩坑里学来的——不加排除项时用户说帮我生成一张产品图模型也会傻乎乎地来调这个 Skill然后画出一堆几何图形完全不是用户要的。触发描述的语言要贴近用户的真实表达。我列了画一个生成一张...的图做个...图标这几种常见说法覆盖了大部分触发场景。你也可以根据自己的使用习惯补充比如来个...示意图。3.3 生成指令的核心结构这是整个 Skill 的心脏。我把原版 Codex Skill 的生成逻辑翻译成了 Claude Code 能执行的指令文本。核心结构分四步第一步解析需求。让模型先从用户描述里提取关键信息主体是什么、有没有动作、有没有场景、风格偏好是什么。比如鹈鹕骑自行车主体是鹈鹕动作是骑道具是自行车场景未指定就默认纯色背景。第二步规划画布与构图。确定viewBox尺寸我一般默认0 0 800 600横版适合大多数场景。然后规划层次背景层、主体层、细节层。这一步是防止元素打架的关键。第三步逐层生成 SVG 元素。按背景到前景的顺序一层层写g分组每个分组里放对应的图形元素。用rect、circle、path、ellipse这些基础图形组合出复杂形状。第四步语法自检。生成完检查标签闭合、坐标是否越界、颜色值是否合法。这一步能拦掉大部分低级错误。我把这四步写进 SKILL.md 的正文部分用清晰的编号和示例说明。指令文本不能太抽象得有具体的例子。比如讲构图时我会写主体元素应占据画布中央约 60% 的区域四周留出呼吸空间而不是笼统地说注意构图。3.4 参数选择与坐标计算的实际过程很多人卡在怎么把一只鹈鹕画出来这一步。这里我分享一个实操中的计算方法以鹈鹕骑自行车为例。画布定800x600。自行车放中间偏下轮子直径设120两个轮子圆心分别在(280, 420)和(520, 420)这样两轮间距240比例协调。车架用path连接两个轮心形成一个三角形结构。鹈鹕坐在车座上身体用ellipse画中心大约在(400, 300)长轴100、短轴70。脖子用path画一条曲线向上延伸头部用circle喙用polygon画一个长三角形。这些数字不是拍脑袋来的而是基于一个简单原则先定大件的位置和尺寸再让细节依附于大件。轮子定了车架就有了锚点车座定了鹈鹕身体就有了落点身体定了脖子和头就有了起点。这样一层层推下去画面就不会散。我在 SKILL.md 里把这个锚点推导法写成了明确的指令让模型按这个顺序思考。实测下来比让它自由发挥稳定太多。自由发挥时模型经常把鹈鹕画得比自行车还大或者轮子飘在半空中。提示坐标计算不需要精确到像素级但要有合理的相对关系。模型对绝对数值不敏感对谁在谁上面、谁比谁大这类相对关系更敏感。指令里多用相对描述少用绝对数值。4. 实操全流程从一句话到一张 SVG4.1 触发 Skill 并生成第一张图环境搭好、SKILL.md 写完之后实操就很简单了。在 Claude Code 里输入画一只鹈鹕骑自行车的插图模型识别到这是插图生成请求加载svg-illustratorSkill然后按指令流程走一遍输出一段完整的 SVG 代码。我实测的首次输出结构大致是这样的svg viewBox0 0 800 600 xmlnshttp://www.w3.org/2000/svg rect width800 height600 fill#f5f5f0/ g idbicycle circle cx280 cy420 r60 fillnone stroke#333 stroke-width6/ circle cx520 cy420 r60 fillnone stroke#333 stroke-width6/ path dM280 420 L400 320 L520 420 fillnone stroke#333 stroke-width6/ ... /g g idpelican ellipse cx400 cy300 rx50 ry35 fill#fff stroke#333 stroke-width4/ ... /g /svg拿到这段代码保存成.svg文件用浏览器打开就能看到图。或者直接嵌进 HTML 里img srcpelican.svg就能显示。4.2 保存、预览与迭代修改生成只是第一步迭代才是常态。第一版出来我发现鹈鹕的喙太短看着像鸭子。这时候不用重新生成直接告诉模型把鹈鹕的喙加长做成向下弯曲的喉囊形状模型会基于上一版代码做局部修改只动喙相关的path其他部分保持不变。这就是 SVG 路线相比位图生成的最大优势——可增量修改。位图你只能重新抽卡SVG 你可以像改代码一样精确调整。我一般的工作流是生成初版 → 浏览器预览 → 指出问题 → 局部修改 → 再预览。通常迭代三到五轮就能得到一张能用的图。整个过程都在 Claude Code 里完成不用切换工具。预览有个小技巧把 SVG 代码存成.html文件里面用img引用然后用浏览器的自动刷新插件盯着改完保存就能立刻看到效果。比每次手动打开文件快得多。4.3 把 SVG 用起来嵌入文档与网页生成的 SVG 有好几种用法。最简单的是当图片用img标签直接引用。但这样有个限制——SVG 内部的样式和脚本不会生效。如果你想让 SVG 支持交互比如悬停变色得用内联方式把svg代码直接写进 HTML。嵌入 Markdown 文档时大多数渲染器支持直接贴 SVG 代码块或者引用.svg文件路径。我写技术文档时经常用这个 Skill 生成示意图比截图清晰比手绘快。还有一个进阶用法把 SVG 当图标库。生成一批风格统一的图标每个存成单独文件然后在项目里按需引用。因为都是同一个 Skill 生成的风格天然一致不会出现这个圆角那个直角的违和感。注意SVG 里如果用了外部字体在别的环境打开可能显示异常。稳妥做法是把文字转成路径或者用系统通用字体族。我一般直接用font-familysans-serif兼容性最好。4.4 批量生成与风格统一单个插图好办批量生成才是考验 Skill 质量的地方。我试过一次性让模型生成一套六个图标结果第一版风格乱得没法看——有的描边粗有的细有的圆角有的直角。解决办法是在 SKILL.md 里加一段风格约定统一描边宽度4统一圆角半径8统一主色#333统一背景透明。把这些约束写死之后批量生成的图标风格就一致了。这跟设计系统里的 Design Token 是一个道理——把可变的东西固定下来输出就稳定了。如果你要做一整套视觉素材建议先让模型生成一个风格样板确认满意后把这个样板的特征颜色、线宽、圆角、留白比例提取出来写进 Skill 指令再批量生成其余的。这样能保证整套素材的视觉一致性。5. 常见问题与排查技巧实录5.1 Skill 不触发怎么办这是最高频的问题。你输入了画图请求模型却跟你聊起天来完全没调用 Skill。排查顺序如下先检查目录路径。.claude/skills/svg-illustrator/SKILL.md这个路径必须一字不差大小写敏感。我见过有人写成.claude/skill/少了个 s结果死活不触发。再检查 frontmatter 格式。---包裹的头部信息name和description字段必须存在且格式正确。YAML 对缩进敏感多一个空格都可能解析失败。最后检查触发描述。如果描述写得太窄比如只写了生成 SVG 图标那你输入画一只鹈鹕就触发不了。把常见表达都列进去覆盖面才够。5.2 生成的 SVG 显示异常显示异常通常有三类原因。第一类是标签未闭合浏览器直接报错白屏。这是模型生成时的低级失误解决办法是在 SKILL.md 里强调生成后必须自检标签闭合。第二类是坐标越界元素跑到画布外面看不见。检查viewBox和元素坐标的关系确保所有元素都在viewBox范围内。第三类是颜色值非法比如写成了#gggggg。这个也是自检环节能拦住的。下面这张表是我整理的常见异常速查现象可能原因排查方法白屏无显示标签未闭合或语法错误用浏览器控制台看报错部分元素消失坐标越界或层级被遮挡检查坐标范围和g顺序颜色不对颜色值非法或拼写错误检查 fill/stroke 属性文字显示异常字体缺失改用通用字体族或转路径整体比例失调viewBox 与元素尺寸不匹配重新规划画布尺寸5.3 输出质量不稳定的应对同样的提示词有时候画得好有时候画得烂。这是指令注入范式的固有特性——模型有发挥空间就有波动。我的应对策略是收紧约束。具体做法在 SKILL.md 里把必须遵守的规则列成清单比如必须使用 viewBox必须分组必须自检。规则越明确波动越小。另外examples/目录里的样例越丰富模型参考得越充分输出越稳定。我放了五六个不同主题的样例后输出质量的方差明显收窄。还有一个技巧是分步生成。不要一次性让模型画完整张图而是先让它规划构图输出文字描述确认后再生成代码。这样你能在早期介入避免它沿着错误方向一路跑到底。5.4 我踩过的几个坑第一个坑是过度依赖模型的空间想象。早期我让模型直接画结果它把鹈鹕的翅膀画到了身体外面。后来我改成先描述每个元素的相对位置再生成代码问题就解决了。模型对文字描述的空间关系理解比对纯几何计算的理解更靠谱。第二个坑是忽略了 SVG 的渲染顺序。SVG 是按代码顺序渲染的后写的盖住先写的。我一开始把背景写在了最后结果整个画面被背景色盖住了。记住背景永远写在最前面。第三个坑是样例文件格式不统一。我早期放的样例有的带 XML 声明有的不带导致模型输出时也跟着摇摆。后来统一了样例格式输出就规范了。提示Skill 调优是个迭代过程别指望一次写完美。我的经验是前三次使用一定会暴露问题根据问题反推指令哪里写得不够明确改完再用三轮下来基本就稳了。6. 这个平替还能怎么扩展跑通基础版之后我陆续加了一些扩展能力这里分享几个我觉得最有价值的。主题配色切换。在 SKILL.md 里加一段配色方案指令让模型根据用户指定的主题比如科技蓝暖阳橙自动调整主色和辅助色。这样同一个 Skill 能产出不同风格的素材不用改代码。尺寸预设。常用的画布尺寸做成预设比如图标用 64x64横幅用 1200x400卡片用 400x300。用户说做个横幅模型自动套用对应尺寸省去每次指定。导出格式转换。SVG 生成后可以再让模型写一段脚本把它转成 PNG 或 PDF。这个用常见的图形处理库就能做适合需要位图格式的场景。与文档工作流集成。我把它接进了自己的文档生成流程——写文档时遇到需要配图的地方直接调用这个 Skill 生成省去了找图、下载、裁剪的环节。整个流程在终端里闭环效率提升很明显。风格迁移。如果你有一套既有的视觉规范可以把规范里的颜色、线宽、圆角、字体等参数提取出来写进 Skill 指令。这样生成的插图天然符合你的品牌规范不用二次调整。这个 Skill 的边界其实取决于你的想象力。它本质上是一个用代码画图的能力凡是能用几何图形组合表达的东西它都能画。流程图、架构图、示意图、图标、简单插画都在射程范围内。写实照片那种还是老老实实用别的方案。我在实际使用中的体会是这个平替最大的价值不在于省了多少钱而在于把插图能力变成了一个可编程、可版本管理、可批量复用的模块。你生成的每一张图都是代码代码可以进 Git可以 review可以 diff。这是位图生成永远做不到的事情。对于需要大量视觉素材又追求一致性的项目来说这条路值得走一遍。