SKILL拆解: 小黑怪诞正文配图
小黑怪诞正文配图 是最近一个很火的技能，能为文章配上精致的图。本篇文章我们就分析这个。
前言
内容较多，比较抽象，为了让大家印象更加深刻，直接用开发者听的懂的方式先说清楚，如果理解了再往下看。
映射关系
注意这里只是举例，类比，不要钻牛角尖。
| SKILL.md 模块 | 映射代码位置 | 代码实现作用/逻辑 |
|---|---|---|
name | 函数名 (def <name>) | 标识函数的唯一标识符，便于 Agent/LLM 调用或框架路由。 |
description | 函数文档注词 (Docstring) | 提供给 LLM 或开发者的使用场景描述，作为 Tool Calling 的 Prompt 依据。 |
技能参考 | 工具注入 / 依赖初始化 | 声明该函数执行时需要的外部工具（如数据库、API、中间件等）。 |
工作流 | 函数体核心代码 (Function Body) | 将自然语言描述的步骤转化为顺序/条件执行的具体业务逻辑。 |
输出口径 | 返回值/格式化输出 (return) | 对最终产生的数据结构做 Response 约束与清洗输出。 |
好了，如果到这里你大家有自己的想法了。我们再看下面就会很简单了。我们带着要写一个好的函数的目的，去看下面内容，就比较容易了。
一、从 SKILL.md 文件中能学到什么
1.1 在 Frontmatter 中写清楚 description
description 不是普通的功能介绍，而是 Skill 的触发条件。
系统需要根据用户当前的请求，判断是否应该加载这个 Skill。因此，description 不能只写一句抽象描述：
1description: 用于生成文章配图。这种描述存在两个问题：
- 能力边界太宽；
- 用户换一种说法后，可能无法正确触发。
参考 Skill 的 description 同时描述了任务对象、使用场景和常见触发词：
1---
2name: ian-xiaohei-illustrations
3description: >
4 生成 Ian 风格的中文正文配图。
5 用于用户要求为中文文章、帖子、博客、Notion 文档、
6 工作流文档、方法论、流程、结构、状态、隐喻或观点生成
7 “怪诞”“小黑”“手绘”“正文配图”“文章插图”
8 “配图建议”“shot list”“去标题”“改图”等任务。
9---这里值得学习的不是具体内容，而是 description 的组织方式。
一个可用的 description 应该包含：
1任务对象
2+ 核心能力
3+ 使用场景
4+ 用户可能使用的触发词
5+ 必要的能力边界例如，用户可能不会准确地说“生成正文配图”，而是会说：
- 给文章加两张图；
- 分析哪些地方需要配图；
- 生成一个 shot list；
- 把这段流程画出来；
- 去掉图片里的标题；
- 修改刚才生成的图。
这些表达在业务上属于同一个 Skill，但在关键词层面并不相同。
因此，description 需要覆盖真实的用户表达，而不是只写一个标准功能名称。
从开发角度看，可以把 description 理解成路由匹配规则：
1用户输入
2 ↓
3description 语义匹配
4 ↓
5决定是否加载 Skilldescription 写得越模糊，路由就越不稳定。
但触发词也不能无限堆积。应该优先覆盖：
- 高频动作；
- 核心任务对象；
- 常见别名；
- 典型修改操作；
- 容易与其他 Skill 混淆的表达。
1.2 SKILL.md 的目录结构必须清晰
SKILL.md 是执行入口，不应该写成一篇没有边界的长文。
常见问题是不断增加标题：
1## 注意事项
2
3## 特殊说明
4
5## 额外要求
6
7## 重要原则
8
9## 一些建议
10
11## 其他情况这些标题看起来是在分类，实际上没有稳定的职责边界。随着规则增加，同一条约束可能同时出现在多个章节中，后续很难维护。
参考 Skill 使用了比较克制的主体结构：
1# Skill 名称
2
3## 核心定位
4
5## 先读这些参考
6
7## 工作流
8
9### 1. 消化正文
10
11### 2. 先出配图策略
12
13### 3. 单张生成
14
15### 4. 检查与迭代
16
17### 5. 保存交付
18
19## 输出口径从开发角度，可以把它进一步抽象为：
1# 技能名称
2
3## 核心定位
4
5## 技能参考
6
7## 工作流
8
9### 1. 作业步骤
10
11### 2. 作业步骤
12
13### 3. 检查作业
14
15### 4. 保存交付
16
17## 输出口径每一级标题都有明确职责。
一级标题：技能名称
一级标题只用于说明当前 Skill 是什么。
一个 SKILL.md 只保留一个一级标题，不要使用多个一级标题拆分内容。
1# 中文文章正文配图二级标题：Skill 的固定组成部分
二级标题用于划分 Skill 的核心模块：
1## 核心定位
2
3## 技能参考
4
5## 工作流
6
7## 输出口径不要为每条规则单独创建二级标题。
二级标题太多通常意味着职责没有归类，或者主文件承担了过多细节。
三级标题：工作流步骤
三级标题主要用于描述工作流中的具体步骤：
1## 工作流
2
3### 1. 读取输入
4
5### 2. 生成方案
6
7### 3. 执行任务
8
9### 4. 检查结果
10
11### 5. 保存交付这种写法有几个好处：
- 执行顺序明确；
- 可以快速定位任务失败在哪一步；
- 后续可以在中间插入新步骤；
- 每个步骤都可以定义输入和输出；
- 更容易转换为脚本或者 Agent 工作流。
标题层级本质上是在表达程序结构。
如果把整个 Skill 看成一个函数，那么二级标题对应主要模块，三级标题对应顺序执行的步骤。
1.3 提示词和参考规则不要全部放进 SKILL.md
参考 Skill 没有把风格、角色、构图、提示词和检查规则全部写在入口文件中，而是拆分到了 references 目录：
1references/
2├── style-dna.md
3├── xiaohei-ip.md
4├── composition-patterns.md
5├── prompt-template.md
6└── qa-checklist.md每个文件只承担一种职责：
| 文件 | 职责 |
|---|---|
style-dna.md | 描述视觉风格和颜色规则 |
xiaohei-ip.md | 描述角色形象和行为约束 |
composition-patterns.md | 描述构图模式和隐喻生成方法 |
prompt-template.md | 描述单次生成使用的提示词模板 |
qa-checklist.md | 描述检查项和失败后的修复方式 |
这种结构符合单一职责原则。
如果所有规则都写进 SKILL.md，后续通常会出现几个问题：
- 主文件越来越长；
- 相同规则重复出现；
- 修改风格时可能影响工作流；
- 修改检查规则时需要在多个位置同步；
- 每次执行都加载大量无关上下文；
- 很难判断某条规则属于哪个环节。
更合理的方式是让 SKILL.md 负责编排，让 references 负责提供领域知识。
1SKILL.md
2负责：什么时候读、先读什么、读完后做什么
3
4references
5负责：具体规则、模板、标准和检查项这和代码中的模块化设计非常接近：
1入口文件负责调用
2业务模块负责实现
3配置文件负责规则
4测试模块负责验证需要注意的是，拆文件并不是越多越好。
判断是否需要拆分，可以看三个条件：
- 这组内容是否具有独立职责；
- 这组内容是否会独立变化；
- 这组内容是否只在部分流程中使用。
如果三个条件都不成立，就没有必要为了目录好看而拆文件。
二、工作流应该如何组织
Skill 的核心不是参考资料，而是工作流。
参考 Skill 的工作流包含三类步骤：
1作业流程
2检查作业
3保存交付这三部分缺一不可。
2.1 作业流程：描述任务如何执行
作业流程负责把用户请求转换成最终产物。
参考 Skill 没有直接从正文跳到图片，而是经过多个步骤：
1读取正文
2 ↓
3提取认知锚点
4 ↓
5决定哪些内容需要配图
6 ↓
7生成配图策略
8 ↓
9调用图片生成工具从开发角度看，这里最重要的是每个步骤都有相对明确的输入和输出。
例如：
1步骤：消化正文
2
3输入：
4- 用户提供的正文
5- Markdown 文件
6- 页面链接
7- 内容截图
8
9处理：
10- 提取核心观点
11- 识别认知转折
12- 判断哪些内容适合用图表达
13
14输出：
15- 候选认知锚点下一步不再直接面对整篇原始正文，而是消费上一步产生的结构化结果。
这种方式比“一次性完成所有任务”更稳定，因为每一步只处理一个问题。
编写工作流时，应该尽量回答：
- 当前步骤读取什么；
- 当前步骤要做什么判断；
- 当前步骤产生什么结果；
- 下一步依赖当前步骤的什么输出；
- 哪些情况下需要进入不同分支。
如果一个步骤只有“认真分析”“深入思考”“确保高质量”这样的描述，它通常还不能执行。
2.2 检查作业：结果必须能够被检查
很多 Skill 只有执行流程，没有检查流程。
任务执行完成后，只要求模型“确保结果符合要求”。这种检查没有明确标准，也不会触发修复动作。
参考 Skill 将检查规则放在独立的 qa-checklist.md 中，检查内容包括：
- 图片比例是否正确；
- 背景是否符合要求；
- 角色是否承担核心动作；
- 画面是否过于复杂；
- 是否只表达一个核心结构；
- 中文标注是否过多；
- 是否错误使用颜色；
- 是否过于接近 PPT；
- 是否复刻历史案例。
这些检查项具备一个共同特点：能够观察。
例如：
1无效检查：
2- 图片是否足够高级
3- 图片是否很有创意
4- 图片是否符合审美
5
6有效检查：
7- 主体是否超过画面约 60%
8- 中文标注是否超过规定数量
9- 左上角是否出现类型标题
10- 角色是否参与核心动作
11- 是否出现复杂背景、渐变或阴影可观察的检查项，才有可能形成稳定的判断。
除此之外，检查作业还需要定义失败后的处理方式：
1太复杂
2→ 删除次要节点，只保留一个核心动作
3
4太像 PPT
5→ 删除标题、边框、网格和多余箭头
6
7角色只是装饰
8→ 重新设计动作，让角色参与核心流程
9
10文字错误过多
11→ 减少标注数量并重新生成因此，完整的检查流程应该是：
1执行完成
2 ↓
3按照检查清单验证
4 ↓
5发现失败项
6 ↓
7执行对应修复动作
8 ↓
9再次检查
10 ↓
11通过后进入交付这和软件开发中的测试流程非常接近：
1实现
2→ 测试
3→ 发现失败
4→ 修复
5→ 回归测试没有检查能力的 Skill，只能生成结果；具备检查和修复能力的 Skill，才有机会稳定交付结果。
2.3 保存交付：执行结果必须有记录
任务通过检查以后，还需要进入保存交付阶段。
参考 Skill 规定了具体保存目录：
1assets/<article-slug>-illustrations/并规定了文件命名方式：
101-topic-name.png
202-topic-name.png同时明确：
- 不要把多张图片拼成一张；
- 保留原始生成文件；
- 默认不要覆盖已有文件；
- 最终返回生成数量、用途和保存位置。
从开发角度看，这一步解决的是结果可追踪问题。
如果 Skill 只在对话中说“已经完成”，但没有明确保存路径、文件名称和执行记录，那么用户很难判断：
- 最终产物在哪里；
- 哪个文件对应哪个任务；
- 是否覆盖了旧文件；
- 哪些结果已经完成；
- 下次执行应该从哪里继续。
因此，保存交付至少应记录：
1产物是什么
2保存在哪里
3使用什么命名
4是否覆盖旧产物
5本次完成了哪些内容
6是否存在失败或可选结果对于涉及文件、外部系统或多步骤任务的 Skill，还应该考虑幂等性。
同一个请求重复执行时，应该明确：
- 复用已有结果；
- 创建新版本；
- 跳过已经完成的步骤；
- 还是覆盖原有产物。
如果没有这类规则，Skill 每执行一次，就可能产生一批重复文件或重复记录。
三、输出口径是 Skill 的返回协议
## 输出口径 描述的不是内容风格，而是 Skill 完成任务后应该向用户返回什么。
参考 Skill 要求最终说明：
- 生成了几张图；
- 每张图有什么用途；
- 文件保存在哪里；
- 哪些结果最稳定；
- 哪些结果属于可选方案。
这相当于一个函数的返回值定义。
如果工作流只定义了内部执行过程，却没有规定最终返回内容，就容易出现两种结果：
- 返回大量执行细节，用户找不到最终产物；
- 只返回“已经完成”，用户不知道具体完成了什么。
一个清晰的输出口径通常包括：
1执行结果
2产物数量
3产物用途
4保存位置
5异常情况
6后续可选动作输出口径应该短而稳定，不需要重复解释整个工作流。
例如：
1## 输出口径
2
3任务完成后，返回：
4
5- 本次生成的文件数量；
6- 每个文件对应的用途；
7- 文件保存路径；
8- 未通过检查或需要人工确认的内容。
9
10不要重复输出完整提示词，不要长篇解释内部执行过程。这样无论 Skill 内部执行了多少步骤，最终都会通过统一格式交付结果。
四、references 设计
references 就相当于我们在开发过程中，能使用的工具。所以函数写的好不好，references 里面写的质量也很重要。看了下面几个文件。我们应该都能总结出来的优点是。
4.1 明确输入输出和标准
- 要什么
- 不要什么
- 判断标准是什么
4.2 职责清晰
如果你是开发者，应该都了解领域驱动，领域驱动其实换句话说就是单一职责。责任划分清楚分配到人。方便替换。(有点不对劲，感觉怪怪的)
4.3 标准化
我们在 SKILL.md 里面看到有这么一行
- references/prompt-template.md：单张生图提示词模板。 prompt-template.md
将抽象的东西，有转换成标准的通用的生图提示词。
4.4 质量可被执行
qa-checklist.md qa-checklist.md：让质量要求可以执行
4.4.1 必过项 & 失败项
1例如：
2
3是否为 16:9；
4是否为白色背景；
5主体是否超过约 60%；
6中文标注是否过多；
7左上角是否出现标题；
8是否存在复杂背景；
9是否使用了过多节点和箭头。这些检查项能够得到相对明确的结果。相比之下，“是否专业”“是否高级”很难直接执行。
可以学习的是：
QA 尽量检查可观察结果，不检查抽象感受。
4.4.2 修复标准
它没有在发现失败后直接统一“重新生成”，而是区分：
1太普通
2→ 增加隐喻，让角色参与核心动作
3
4太复杂
5→ 删除节点和标注
6
7太可爱
8→ 调整角色气质
9
10太像 PPT
11→ 删除标题、网格、边框和多余箭头
12
13文字错误
14→ 局部编辑，严重时减少文字后重生成4.5 可以直接提炼的 references 设计原则
以后设计 references，可以使用下面这套判断：
1全局必须一致的规则
2→ 独立规范文件
3
4核心对象的属性和行为
5→ 独立领域模型文件
6
7需要根据场景选择的方案
8→ 独立策略文件
9
10提交给外部工具的请求
11→ 独立模板文件
12
13结果是否合格
14→ 独立 QA 文件| 文件类型 | 应回答的问题 |
|---|---|
| 规范 | 最终结果必须满足什么 |
| 领域模型 | 核心对象是什么、能做什么、不能做什么 |
| 策略 | 不同场景应该选择哪种处理方式 |
| 模板 | 如何把任务参数转换成工具输入 |
| QA | 如何检查、失败后如何修复 |
五、总结
前言部分比较清晰，如果你有开发经验，看到 SKILL.md 与函数结构的映射关系，基本一眼就能明白。
正文读起来会稍显枯燥，因为大部分内容都在分析具体规则和实现细节。这些细节有些可以复用，有些只适用于当前的配图场景。我们不需要照搬所有内容，重点是理解它的设计思路。
从整体来看，这个 Skill 的职责划分、目录结构、工作流和交付标准都很清晰，值得单独用一篇文章进行拆解。
这只是单个 Skill 的分析。后面会继续提高难度，开始研究工具组，以及多个 Skill 之间如何分工、传递上下文和协同完成任务。