一、三类各管什么

参考型：内容多、结构稳、按需查。 典型代表是代码审查——它有几十条细目、一堆案例，但每次只需要其中几条。 任务型：有明确动作序列、每步有判据。典型代表是智能提交——读改动、归类、写信息、提交。 复合型：入口分几类、每类做法不同。典型代表是财务分析——对账走一条路，汇总走另一条路。

三类的区别不在内容多少，在信息该怎么被取用：查的、做的、还是先分再查。

二、参考型：代码审查

结构是「薄正文加厚 refs」：正文只写怎么判断、什么情况该去翻哪份文件，细目和案例全放 refs。 演示里这份正文十五行、一百八十六 token，refs 里躺着一份二十四条细目和十二个案例。 正文短是有意的：正文每次触发都要读，refs 只有模型真的去翻才读。 把重内容放 refs，等于把「要不要读」这个决定交给了当场的情况。

判据也很清楚：正文里只放「怎么判断」，具体条目全放 refs。如果正文里出现了第十条细目， 说明它已经开始变成仓库了。 这类技能最容易写坏的方式是「怕漏」。 作者担心模型找不到细目，就把二十四条全抄进正文，于是每次触发都读一遍全部。

三、任务型：智能提交

结构是「编号步骤加每一步的命令和判据」，最后再给几条「不要做」。 演示里这份十四行、二百一十五 token、五条编号步骤、零个 refs——它不需要 refs， 因为全部内容就是这五步。 这类技能最怕的是「步骤里带判断」。 比如第三步写「按改动内容归类」——这是一个需要理解的动作，模型能做得不错，但它每次做的可能不一样。

能固化的尽量固化：把六种前缀列出来（feat、fix、docs、refactor、test、chore）， 比说「选一个合适的」强得多。 判据是：每一步结束时，能不能明确判断「这步做完了没有」。能，就是一条合格的步骤； 不能，那它其实是一段需要人拿主意的判断。

四、复合型：财务分析

结构是「第一段路由器加后面两三条支路」，每条支路引用自己的 refs。 演示里这份十六行、二百一十 token：第一段就是分流——对账走一个文件，汇总走另一个，其他情况先问一句。 这样写的好处是，一次触发只读一个 refs 文件，另一个不读。 如果两份都读，等于把两个技能的成本硬凑成一个。

难度在分流条件要可判定。 「用户说对账、核对、差异」可以判，「用户想做财务相关的事」判不了——那等于没有分流。 所以复合型的第一段必须写成一组可判定的条件，而不是一句概括。 写不出可判定的条件，说明这不是一个复合型技能，是两个技能。

五、三份并排看

指标一摆，差别很清楚：参考型十五行、三个二级标题、四条编号步骤、两个引用文件； 任务型十四行、两个二级标题、五条编号步骤、零引用； 复合型十六行、三个二级标题、零编号步骤、四个引用。 参考型的「编号步骤四条」是判断流程，不是动作序列——它回答「从哪看起」，不回答「先做什么再做什么」。 三类各有各的形状。反过来看也成立：看到一个技能正文的形状，就能猜出它属于哪一类。

六、建完之后扫一遍

三份建完，跑一次扫描，三份都在。扫描器认的是「任意层目录下有一个 SKILL.md」。 所以 refs 里的文件不会被误认成技能——这也是为什么参考文件要放在技能目录内部的子目录里， 而不是平行放。 这带来一个实用的约定：一个技能的所有东西都收在自己的目录下。要分享，打包一个目录就够了； 要删，删一个目录就干净了。

演示最后打了一遍正文字数：二百一十二、二百九十四、二百五十六。 三份都不长，因为它们都把该外置的东西外置了。

七、动手 Demo：三类技能各建一份，看结构差在哪

在一个临时目录里建三个技能：code-review（参考型，带 refs）、git-commit（任务型）、 monthly-reconcile（复合型，带两份 refs）。 先看目录树，再数三份正文的结构指标，最后跑一次扫描确认三个都在。

def build(root):
    put(root, u"code-review/SKILL.md", SK_REVIEW)
    put(root, u"code-review/refs/checklist.md", CHECK)
    put(root, u"code-review/refs/examples.md", EXAMP)
    put(root, u"git-commit/SKILL.md", SK_COMMIT)
    put(root, u"monthly-reconcile/SKILL.md", SK_RECON)
    put(root, u"monthly-reconcile/refs/reconcile.md", RECON)
    put(root, u"monthly-reconcile/refs/summary.md", SUMM)

实跑输出：

--------------------------------------------------------------------
三类技能各建一份，看结构差在哪
--------------------------------------------------------------------


  ① 建出来的目录
  --------------------------------------------------------------------
  ├── code-review/
  │   ├── SKILL.md
  │   └── refs/
  │       ├── checklist.md
  │       └── examples.md
  ├── git-commit/
  │   └── SKILL.md
  └── monthly-reconcile/
      ├── SKILL.md
      └── refs/
          ├── reconcile.md
          └── summary.md

  ② 三份正文的结构指标
  --------------------------------------------------------------------
| 类型 | 行数 | 二级标题 | 编号步骤 | 引用文件 | token |
|---|---:|---:|---:|---:|---:|
| 参考型 | 15 | 3 | 4 | 2 | 186 |
| 任务型 | 14 | 2 | 5 | 0 | 215 |
| 复合型 | 16 | 3 | 0 | 4 | 210 |

  三类各有各的形状：参考型没有编号步骤（它给的是判据），任务型全是编号步骤（它给的是动作），
  复合型先分流再给规则。

  ③ 参考型：正文薄，重量在 refs
  --------------------------------------------------------------------
  code-review 的正文只有 186 token，但 refs 里躺着一份二十四条细目和十二个案例。
  这是有意的：正文每次触发都要读，refs 只有模型真的去翻才读。
  把重内容放 refs，等于把「要不要读」这个决定交给了当场的情况。
  ! 参考型的判据：正文里只放「怎么判断」，具体条目全放 refs。
  如果正文里出现了第十条细目，说明它已经开始变成仓库了。

  ④ 任务型：全是动作，没有解释
  --------------------------------------------------------------------
  git-commit 那份五步，每步一条命令加一句判据，最后还有三条「不要做」。
  这类技能最怕的是「步骤里带判断」。
  比如第 3 步「按改动内容归类」——这是一个需要理解的动作，模型能做得不错，但它每次做的可能不一样。
  能固化的尽量固化：把六种前缀列出来，比说「选一个合适的」强得多。

  ⑤ 复合型：第一段是路由器
  --------------------------------------------------------------------
  monthly-reconcile 的第一段就是分流：对账走一个文件，汇总走另一个，其他情况先问一句。
  这样写的好处是，一次触发只读一个 refs 文件，另一个不读。
  如果两份都读，等于把两个技能的成本硬凑成一个。
  ! 复合型的难度在【分流条件要可判定】。
  「用户说对账、核对、差异」可以判，「用户想做财务相关的事」判不了——那等于没有分流。

  ⑥ 扫描一下，三个都在
  --------------------------------------------------------------------
| 技能 | 正文字数 | 路径 |
|---|---:|---|
| code-review | 212 | code-review/SKILL.md |
| git-commit | 294 | git-commit/SKILL.md |
| monthly-reconcile | 256 | monthly-reconcile/SKILL.md |

  扫描器认的是「任意层目录下有一个 SKILL.md」，所以 refs 里的文件不会被误认成技能。
  这也是为什么参考文件要放在技能目录内部的子目录里，而不是平行放。

①目录树里能看出一件事：参考型和复合型都带 refs 子目录，任务型没有。 这不是规定，是内容性质决定的——任务型的内容就是那几步，没有「要深究的部分」。 ②三份的结构指标：参考型十五行、三个二级标题、四条编号步骤、两个引用； 任务型十四行、两个二级标题、五条编号步骤、零引用； 复合型十六行、三个二级标题、零编号步骤、四个引用。 三类各有各的形状：参考型没有编号步骤（它给的是判据），任务型全是编号步骤（它给的是动作）， 复合型先分流再给规则。 ③参考型正文只有一百八十六 token，重量全在 refs 里。 正文每次触发都读，refs 只有真去翻才读——把「要不要读」这个决定交给当场的情况。 ④任务型五步，每步一条命令加一句判据。 这类技能最怕「步骤里带判断」——「按改动内容归类」这种动作每次做的可能不一样。 能固化就固化，六种前缀列出来比说「选一个合适的」强。 ⑤复合型第一段就是分流：对账走一个文件，汇总走另一个。好处是一次触发只读一个 refs。 难度在分流条件要可判定。 「用户说对账、核对、差异」可以判，「用户想做财务相关的事」判不了——那等于没有分流。 ⑥扫描确认三个都在。 扫描器认的是「任意层目录下有一个 SKILL.md」，所以 refs 里的文件不会被误认成技能。 这也是为什么参考文件要放在技能目录内部的子目录里，而不是平行放。 一个技能的所有东西收在自己的目录下，分享和删除都干净。

30 秒实验

1. 把 code-review 的二十四条细目全搬进正文，重跑第 ② 步。行数和 token 各涨到多少？ 触发一次的成本涨几倍？
2. 给 git-commit 的第三步写死六种前缀，重跑一遍。它比「选一个合适的」多花了多少 token？ 换来的是什么？
3. 把 monthly-reconcile 的分流条件改成「用户想做财务相关的事」，重跑第 ⑤ 步。这个条件能被判定吗？ 如果不能，该怎么改？

常见误区

1. 把参考型的细目全抄进正文。正文每次触发都读，抄进去等于每次都读全部，refs 就白设了。
2. 任务型的步骤里留「合适的」「恰当的」这类词。这不是步骤，是需要人拿主意的判断。
3. 复合型的分流条件写成一句概括（「跟财务有关的」）。判不了的条件下等于没有分流。
4. 把 refs 平行放在技能目录旁边。扫描器会误认，分享和删除也会漏。
5. 以为三类是三种「难度」。它们是三种信息形状，选错形状的代价是成本或可靠性。

三份建完了，下一节把它们抽象成四种设计模式，看什么时候该用哪种形状。

• ☐ （本篇完，下一篇 3.10 Skills 的 4 种设计模式）

相关笔记

• 正文的形状：正文是路由器
• 四种设计模式：四种设计模式
• Skill 提效实战 · 索引
• 🐎 Claude Code 实战 · 索引