Skill 的质量不是想出来的，是跑出来的（5/7）

让骨架跑起来：references 怎么写，以及 skill 质量的真实来源——跑出来的 Gotchas

上节课留了一个指针

第 4 课的骨架里，第 2 步写着”按 references/wechat-rules.md 的规则逐段转换”，但那个文件当时不存在。这节课的第一件事：把它真正写出来。这正好是体验三层模型的完整闭环——正文指过来，第三层接住。

references 文件怎么写

references/ 里的文件和正文有不同的写法要求。正文是指令（祈使句、步骤化），references 是查阅资料——agent 在干活途中打开它，快速找到某条具体规则。写法要点：

• 按主题分文件，不按流程分。wechat-rules.md 管排版规则，以后如果要做封面图规范，新开 wechat-cover.md，别往一个文件里堆
• 每条规则自成一体。agent 可能只读到其中一段，每条规则要独立成立，不依赖上下文
• 表格优于段落。查阅型资料里，一个对照表比三段文字好用
• 控制在 ~1000 tokens 以内，超了就进行拆分（业界实践的常见阈值）

以贯穿案例为例，references/wechat-rules.md 的第一版可以长这样：

# 公众号排版规则

## 代码块
公众号编辑器不支持代码高亮。转换时：
- 用等宽字体 + 浅灰背景色的预格式化块
- 行内代码用 `backtick` 样式保留

## 表格
公众号内 HTML 表格会变形。优先级：
1. 三列以内 → 转为定义式段落（项：值）
2. 超过三列 → 提示用户考虑转为图片

## 外链
正文不支持可点击外链。处理：
- [文字](url) → 文字（url 以括号附录形式保留）
- 文末统一列出"文中提到的链接"

实跑：skill 质量的真实来源

骨架 + references 写完，skill 就能跑了。接下来的动作才是 skill 从”能跑”到”好用”的分水岭：拿真实材料跑一遍，收集翻车现场。

迭代循环：
1. 找一篇真实文章（比如一篇旧公众号文章的 md 源文件）
2. 在新会话里触发 skill，让它转换
3. 检查产出，记录每一个"不对"的地方
4. 每个"不对"归类：
   - 规则缺失    → 补进 references
   - 规则有但没执行 → 强化正文步骤里的检查点
   - 反直觉的坑   → 写进 Gotchas
5. 再跑一遍，验证修复

迭代什么时候算够

一个实用的停止标准：同一篇测试文章连续两次转换，找不出需要手动修的地方。注意不是”产出完美”——而是”产出不需要人再动手”。还有一个防过拟合的补充：换一篇没测过的文章再跑，能泛化才算真的教会了 agent，而不是教会了 agent 应付这一篇。

检验一下

## {主题}
{现象/原因一句话}。处理：
1. {可执行步骤}
2. {可执行步骤}

真实材料跑一遍 → 记录每个"不对" → 归类修复：
  规则缺失      → 补 references
  规则有没执行  → 强化正文检查点
  反直觉的坑    → 写进 Gotchas
→ 再跑验证