一、先算一笔账：知识不是免费的

把项目里所有「模型应该知道」的东西列出来，通常会列到十几条：命令怎么跑、代码风格、提交信息格式、 API 设计规范、部署要查什么、数据库表结构、公司手册…… 这些看着都该写进 CLAUDE.md。 但 CLAUDE.md 是常驻的——每次会话开始都要读一遍，三十轮的会话就是读三十遍。 所以「该不该写进去」这个问题，等价于「这份东西值不值得每次会话都读一遍」。

答案对大部分内容是否定的。部署自检流程一周用三次，没必要在另外二十七次会话里陪着。 这就引出两个维度：多久用一次（频率），一次要读多长（体积）。成本是两者的乘积。

二、成本是频率乘长度

演示里把十条知识排在表里，每条给两个数：一周用几次、一次多少 token。 乘出来的周成本，排序很有意思：最贵的不是写得最长的那条，而是又长又常用的那条。 数据库表结构一周用二十次、一次两千五，一周五万。 公司手册两万 token，但一周只用零点二次，一周才四千。

所以「这条很重要」和「这条该常驻」是两件事。重要只影响频率，不影响体积；要常驻得两个都小。 按这个判据分下来，十条里能常驻的只有三条，全是又短又常用的：命令速查、风格约定、提交信息规范。

三、另外七条去哪了

四条去了「按需」：API 设计规范、部署自检、结算单整理、故障复盘模板。 它们有明确的触发场景，一年用几十次，一次读几百 token。 三条去了「检索」：数据库表结构、公司手册全文、历史事故档案。 它们太大，连「一次读全文」都不划算，得先查再读一小段。 四种放法的差别，说到底是读的次数不同：常驻是每次会话读，按需是触发时读，检索是用到哪段读哪段。

演示第 ③ 段算了总账：十条全常驻，一周八十万 token；分层之后两万，差四十倍。 这个四十倍不是「省了内容」，内容和原来一模一样，只是不再每次都读。

四、技能是「按需」那一档的落地形态

「按需」这三个字听着抽象，落到实现上就是一个目录：里面一份 SKILL.md， 头上写清楚「什么时候该用它」，正文写「用它的时候做什么」。 它平时不在上下文里，只留一行描述。模型判断这次用得上，才把正文读进来。 所以技能的第一价值不是「能力更强」，是「不占常驻预算」。 它让「一年用几十次的知识」也能被写下来，而不用为它每轮付钱。

反过来说：一条知识如果每次会话都要用，写成技能反而更贵——每次都得先判断、再加载， 还多了一层不确定性。 这就给出了分界线的下半句：常用而短的进 CLAUDE.md，偶尔用而长的进技能。

五、分界线上容易站错的三处

第一处是把「流程」当「约定」。 约定是几句话（金额用 Decimal），流程是一串动作（先备份、再迁移、再验证、最后回滚演练）。 前者常驻，后者必须是技能。 第二处是把「参考数据」当「规则」。表结构、字段含义、枚举值，这些是查的，不是记的。 写进 CLAUDE.md 只会在每次会话里占掉几千 token，而九成会话根本用不到。 第三处是把「这次的要求」当「长期的规矩」。这次只改 README，这句话属于会话，不属于任何文件。 写进 CLAUDE.md 之后，下次会话会莫名其妙地不敢动代码。

三处的共同点：都是把「偶尔」的东西放进了「每次」的位置。

六、所以这一章要解决的问题

技能这套机制本身不复杂：一个目录、一份带 YAML 头的 Markdown。 难的是三件事——写什么、什么时候被选中、被选中之后读多少。 3.2 解剖结构，3.3 讲三级披露怎么分层付费，3.4 讲触发是怎么决定的，3.5 讲正文该写成什么形状， 3.6 讲权限怎么收窄。 这五节讲完，一个技能从「能写出来」到「能被正确触发」的路就走通了。

后面 3.7 到 3.12 是加法和收尾：参数、作用域、三类实战、设计模式、测试迭代、工程原则。

七、动手 Demo：十条知识，各自该放哪一层

造十条项目里常见的知识，每条给两个数：一周用几次、一次读多少 token。 按「两个都小才常驻」的判据分流，再算一遍总账：全常驻和分层之后差多少。 会话次数按一周二十次估，检索一次按只捞回两百 token 算。

KNOW = [(u"项目命令速查", 50, 120), (u"代码风格约定", 50, 200),
        (u"数据库表结构", 20, 2500), (u"公司手册全文", 0.2, 20000)]

def kind(freq, size):
    if freq >= 20 and size < 300:
        return u"常驻（CLAUDE.md）"   # 又短又常用
    if freq >= 0.5 and size < 1500:
        return u"按需（技能）"        # 有场景，但不必每轮都在
    return u"检索（或子智能体）"      # 太大，先查再读

实跑输出：

--------------------------------------------------------------------
十条知识，各自该放哪一层
--------------------------------------------------------------------

  知识有两个维度：多久用一次、一次要读多长。两个都小，才值得常驻。
| 知识 | 次/周 | 单次 token | 周成本 | 该放哪 |
|---|---:|---:|---:|---|
| 项目命令速查 | 50 | 120 | 6000 | 常驻（CLAUDE.md） |
| 代码风格约定 | 50 | 200 | 10000 | 常驻（CLAUDE.md） |
| 提交信息规范 | 30 | 150 | 4500 | 常驻（CLAUDE.md） |
| API 设计规范 | 5 | 900 | 4500 | 按需（技能） |
| 部署自检流程 | 3 | 450 | 1350 | 按需（技能） |
| 结算单整理 | 1 | 400 | 400 | 按需（技能） |
| 故障复盘模板 | 0.5 | 600 | 300 | 按需（技能） |
| 数据库表结构 | 20 | 2500 | 50000 | 检索（或子智能体） |
| 公司手册全文 | 0.2 | 20000 | 4000 | 检索（或子智能体） |
| 历史事故档案 | 0.1 | 15000 | 1500 | 检索（或子智能体） |


  ① 按周成本排序，界线自己就出来了
  --------------------------------------------------------------------
  数据库表结构         一周 50000 token
  代码风格约定         一周 10000 token
  项目命令速查         一周 6000 token
  提交信息规范         一周 4500 token
  最贵的四条里，最贵的那条不是「写得长」，而是「又长又常用」。
  数据库表结构一周二十次、一次两千五，一周五万——这条要是常驻，光它一个就把窗口吃掉一半。

  ② 三类各占几条
  --------------------------------------------------------------------
| 放法 | 条数 |
|---|---:|
| 按需（技能） | 4 |
| 常驻（CLAUDE.md） | 3 |
| 检索（或子智能体） | 3 |

  十条里能常驻的只有三条，全是又短又常用的。这个比例在任何项目里都差不多。
  ! 所以「把知识全写进 CLAUDE.md」这个做法，从一开始就注定只有一小部分该在里面。
  剩下的不是不重要，是不该每轮都在。

  ③ 换个角度看：读的次数决定成本
  --------------------------------------------------------------------
| 放法 | 一周读几次 | 一次读多少 | 一周 token |
|---|---:|---:|---:|
| 十条全常驻 | 20 | 40320 | 806400 |
| 那三条常驻 | 20 | 470 | 9400 |
| 那四条按需 | — | — | 6550 |
| 那三条检索 | — | — | 4060 |

  全部常驻一周 806400 token；分层之后是 20010，前者是后者的 40.3 倍。
  差别不在「省了内容」，在「减了次数」：常驻的东西每次会话都要读，按需的那些一年只读几十次，
  检索回来的更只是一小段。
  ! 这正是技能存在的全部理由：它把「随时可得」换成了「要用再取」。
  代价是取的时候多一步判断——那一步就是下一节要讲的触发。

①周成本一排序，界线自己就出来了。 最贵的是数据库表结构，一周五万——它一周用二十次，一次两千五，两个数都不小。 对比公司手册：两万 token，比表结构大八倍，但一周只用零点二次，周成本四千， 反而比「代码风格约定」还低。 所以「这条重要」推不出「这条该常驻」。重要只说明用得多，还得看一次读多长。 ②分流结果：常驻三条、按需四条、检索三条。三比四比三，常驻只占三成。 这个比例在任何真实项目里都差不多——能常驻的永远是少数，因为常驻的门槛是「又短又常用」， 两个条件同时满足的知识本来就少。 ③总账那一段是这一节的落点：十条全常驻一周八十万 token，分层之后两万，差四十倍。 注意这四十倍不是靠删内容省出来的，十条一条没少，只是其中七条不再每次会话都读。 换个说法：技能省的不是存储，是重复读取。这也解释了为什么技能越多， 越要盯着描述的长度——描述是常驻的那一部分，它是唯一还在交税的地方。

30 秒实验

1. 把会话次数从二十改成五次，重跑第 ③ 步。四十倍的差距变成多少？这说明分层的收益取决于什么？
2. 把「数据库表结构」的单次 token 从两千五降到三百，它会从「检索」跳到「常驻」吗？ 跳过去之后周成本是多少？
3. 再加一条「一周用两百次、一次五十 token」的知识，它该放哪？如果放常驻，一周成本多少？

常见误区

1. 把技能当成「更高级的 CLAUDE.md」，于是把该常驻的规矩也搬进技能。 常驻内容搬进技能，等于每次都要多一次「判断要不要用」的往返，反而更贵。
2. 按「重要程度」决定放哪一层。重要只影响频率，不影响体积；常驻的门槛是频率和体积两个都小。
3. 把参考数据（表结构、字段含义）写进常驻文件。 这些是查的，不是记的，写进去只是把几千 token 摆在每次会话里。
4. 以为技能省钱是因为「内容没读」。内容一样要读，省的是没用到的那几十次不读。
5. 技能装得越多越好。 技能数量直接乘在常驻的描述预算上，装二十个用不上的，等于每次会话都在为它们付费。

知道了技能该放什么，下一节把它拆开看：一个技能到底由哪几块拼成。

• ☐ （本篇完，下一篇 3.2 解剖一个 Skill：骨骼与纹理）

相关笔记

• 为什么需要记忆：为什么必须往外搬
• 解剖一个 Skill：一个技能就是一个目录
• Skill 提效实战 · 索引
• 🐎 Claude Code 实战 · 索引