Claude Code 高手都在用的 Reference 管理术

我有一套写作技巧库。

上百种输出技巧——反差钩子、痛点开头、打脸三段式、心象图比喻、去 AI 味审校清单、爽感密度控制……每一个都是从爆款文章里拆出来、反复验证过的。

加上风格指南、案例拆解、审校 SOP，全部加起来，远超 Claude 200K 的上下文上限。

不是"读了有点浪费"——是根本读不完。

就算你把 context 撑满了硬塞进去，AI 也用不出来。信息量太大，它消化不了。25 个技巧同时灌进去，它不知道现在该用哪个，写出来的东西四不像。

所以你做了一个看起来合理的选择：精简。只留最核心的几个技巧，其他的删掉。

但你花了三个月提炼的技巧库，就这么砍成了残废版。

这就是大部分 Skill 玩家卡在的地方：

技巧太多，AI 装不下。砍掉又不甘心。你明明有一整座弹药库，但每次只能带三发子弹上战场。

有没有办法让 AI 不用全部读完，但在需要的时候精准拿到对的那一个技巧？

有。我踩了三次坑才找到。

三次翻车，一个发现

第一次翻车，是在写作项目里。

我给写作 Skill 配了大量参考资料——写作模板、爆款案例拆解、风格指南，全放进 reference。结果每次写文章，AI 上来就把所有模板全读一遍，读完了才开始动笔。你说"帮我写个开头"，它先花 5 分钟把 10 个模板从头到尾看一遍。

第二次翻车，是在短剧改编项目里。

原著有几十个章节，改编规则又是另一套文件。全塞进 reference 后，每次调用，AI 都把所有章节和所有规则都读一遍。我只是想让它改编第 5 章，它把第 1 到第 30 章都扫了一遍。

第三次翻车，是一个知识体系很庞大的 Skill。

所有知识全写在 Skill 正文里——894 行，31KB。每次加载这一个 Skill 就吃掉将近 3 万 token。而实际上大部分调用只用到其中 20% 的知识。

三次翻车，指向同一个问题：Claude Code 不会自动"按需读取"你的 reference 文件。

这不是 bug。这是你没教它怎么读。

转折：Skill 里藏了一个被 99% 的人忽略的原生机制

翻了三次车之后，我去翻 Skill 的加载逻辑，想搞清楚它到底是怎么处理 reference 的。

然后我发现了一个东西。

Skill 的加载机制里，天生就藏着一个"分层读取"的设计。 有些信息它每次都读，有些信息它等你主动调用才读。平台已经把架子搭好了——但 99% 的人不知道这个架子存在，所以要么全塞正文（架子白搭），要么 reference 随便扔进去（架子没用上）。

一旦你理解了这个机制的运作方式，你就能顺着它去设计——让 AI 不需要读完所有资料，但在需要的时候，精准拿到对的那一份。

我把这套方法用在了那个 894 行的 Skill 上：

• 正文从 894 行降到 ~450 行
• 每次加载从 31KB 降到 ~17KB
• 省了 45%-50% 的 token

关键是——AI 的回答质量没掉。甚至更精准了。因为它不再被 900 行信息淹没，而是只读当下最需要的那一份。

这个机制叫什么？怎么激活？核心的设计诀窍在哪？

下面一层一层拆。

核心概念：渐进式披露

先揭底。

免费部分提到的那个"被 99% 的人忽略的原生机制"，有个名字——渐进式披露（Progressive Disclosure）。

什么意思？就是不一次性把所有信息倒给你，而是一层一层地、在你需要的时候才展开下一层。

Skill 的加载机制天生就是这么设计的。来看 Claude Code 加载一个 Skill 时到底读了啥：

| 步骤 | 读什么 | 是否自动读 | |------|--------|-----------| | 第 1 步 | Skill 正文（SKILL.md 的内容） | 自动，每次都读 | | 第 2 步 | 每个 reference 的 description 字段 | 自动，每次都读 | | 第 3 步 | reference 文件本身（.md 文件内容） | 不自动，需要 AI 主动用 Read 工具打开 |

看到没？前两步是自动的，第三步不是。

三层，从轻到重，从必读到可选。平台已经帮你把渐进式披露的架子搭好了。

但大部分人不知道这个架子存在。所以要么跳过中间层（description 随便写两个字），要么绕过整个机制（全塞正文里）。

你要做的，不是发明什么新东西，而是顺着这个已有的机制去设计。具体怎么设计？先用个比喻来理解整体逻辑：

Skill 正文  = 图书馆的导航图（贴在墙上，进门就能看到）
description = 每个书架的目录牌（走过去就能看到）
reference   = 书架上的书（需要伸手去拿才能看到内容）

AI 进了图书馆，导航图和目录牌都看得到。但书，它得自己判断"拿哪本"，然后主动伸手去拿。

导航图上没写"历史类在 3 楼"？它不知道该上哪层。目录牌上只写了"资料合集"四个字？它也不知道这个书架上到底有什么。

所以你塞了 10 个 reference，AI 要么全读——不知道该读哪个，保险起见全搬；要么不读——正文没提，它就不确定要不要打开。

三层金字塔架构，就是给 AI 一张好用的导航图 + 有信息量的目录牌。

第 1 层：规则层——写在 Skill 正文里

每次调用，AI 都会读到这层。它是整个架构的"指挥中枢"。

这层必须塞进两个"指挥棒"，少一个都不行。

指挥棒 1：资料使用规则

你需要在 Skill 正文里显式写一段话，告诉 AI 怎么对待 reference 文件：

## 资料使用规则（必须遵守）
 
1. 不要一次性读所有 reference 文件
2. 先看每个 reference 的 description
3. 只打开与当前任务直接相关的 1-2 个文件
4. 如果不确定该看哪个，先问用户

就这四句话。简单到你觉得"这也要写？"

但不写的后果你已经体验过了——AI 要么全读要么不读。这四句话是让 AI 从"要么全读要么不读"变成"精准读取"的开关。

指挥棒 2：场景路由表

光告诉 AI "按需读取"还不够。它需要知道——什么场景该读什么文件。

你得在正文里画一张"路由表"：

### 场景路由表
 
| 用户任务类型 | 该查哪个 reference |
|-------------|-------------------|
| 写文章开头 | 写作技巧-开头钩子.md |
| 设计文章结构 | 写作技巧-结构框架.md |
| 润色/去AI味 | 写作技巧-去AI味清单.md |
| 选题分析 | 爆款案例分析库.md |

这张表的作用是什么？

AI 收到用户任务后，先看路由表，把任务类型匹配上对应的 reference 文件，然后只打开那一个文件去读。

没有这张表，AI 的判断全靠猜。有了这张表，AI 按图索骥。

这两个指挥棒加在一起，大概只有 10-20 行。但它们是整个三层架构的核心——没有它们，后面两层做得再好也白搭。

第 2 层：索引层——reference 的 description

索引层是 AI 每次都能自动看到的第二道信息。

很多人写 description 是这样的：

references:
  - path: "references/写作技巧.md"
    description: "写作技巧合集"

"写作技巧合集"——这五个字，AI 看了跟没看一样。它不知道什么时候该打开这个文件，也不知道里面到底有什么。等于没写。

这种 description 不叫描述，叫废话。

好的 description 不是"导航卡片"——它是一条强化指令。AI 看一眼就知道四件事：什么时候必须看、里面有什么、跟什么场景相关、不看会搞砸什么。

Description 四要素公式

强化型 description = 【何时查阅】+ 【内容概要】+ 【不读后果】+ 【关键词】

第四个要素是关键。【不读后果】是渐进式披露的"强化指令"——它不是温柔地建议 AI "可以看看"，而是明确告诉 AI "这个场景你不看这个文件，输出就会有什么问题"。

来看对比：

# ❌ 废话 description（AI 看了跟没看一样）
references:
  - path: "references/写作技巧.md"
    description: "写作技巧合集"
 
# ✅ 强化型 description（渐进式披露 + 调用约束）
references:
  - path: "references/写作技巧-开头钩子.md"
    description: |
      【何时查阅】当需要写文章开头、设计悬念钩子时
      【内容概要】12种开头钩子模板 + 5个爆款案例拆解
      【不读后果】不读此文件直接写开头 = 只会用"你有没有遇到过..."这种烂大街套路
      【关键词】开头、钩子、悬念、第一段、吸引力

看到区别了吗？

第一种写法，AI 收到"帮我写个开头"这个任务时，看到"写作技巧合集"五个字——它判断不了这个文件跟"写开头"有没有关系。

第二种写法，四层信息全给了：该看（写开头时）、有什么（12种模板）、不看会怎样（写出烂大街套路）、关键词命中。AI 不需要猜。

特别是【不读后果】这一条——它给 AI 制造了一个"不读 = 搞砸"的约束。这不是可选的建议，是一个强化指令。AI 看到"不读此文件 = 输出质量下降"，它就不敢跳过。

Description 写得好不好，直接决定了渐进式披露机制能不能真正生效。 这是索引层的全部价值。

第 3 层：详情层——reference 文件本身

详情层是完整的参考资料，只在需要的时候才被 AI 打开。

这层的设计原则很简单：

原则 1：一个文件一个主题

不要搞大杂烩。 一个文件里塞了"开头技巧 + 结尾技巧 + 排版规范"，AI 只想看开头技巧，却被迫读了一堆无关内容。

拆开。开头技巧一个文件，结尾技巧一个文件。

原则 2：文件名要有辨识度

❌ 参考1.md
❌ 资料合集.md
❌ 备忘录.md

✅ 写作技巧-开头钩子.md
✅ 写作技巧-去AI味清单.md
✅ 爆款案例-2024年AI主题Top10.md

文件名本身就应该是 description 的缩略版。AI 看到文件名就能猜个大概。

原则 3：超过 500 行就考虑拆

单个 reference 文件太大，AI 打开一个就要吃掉大量 token，跟"全写在正文里"没本质区别。

经验法则：一个 reference 文件控制在 200-500 行之间。超过 500 行？找找能不能按子主题再拆。

实战：从 894 行到 450 行

原理讲完了。来看实操。

我有一个知识密集型 Skill，涵盖了一整套知识体系。最初所有内容全写在 Skill 正文里——894 行，31KB。

每次调用，不管用户问什么问题，AI 都要先读完这 894 行。

拆分思路

第一步：区分"每次都需要"和"偶尔才需要"的内容。

| 保留在正文（每次都读） | 拆到 reference（按需读取） | |---------------------|--------------------------| | 核心身份定位 | 知识体系模块 A（专题知识） | | 工作流框架 | 知识体系模块 B（应用场景） | | 运行原则（关键规则） | 知识体系模块 C（话术与技巧） | | 资料使用规则 + 场景路由表 | 场景策略库 1（特定领域场景） | | 分析框架索引（精简版） | 场景策略库 2（执行与防御场景） |

关键点：资料使用规则和场景路由表必须留在正文里。 这是指挥棒，不能拆出去。

第二步：给每个 reference 文件写导航级 description。

references:
  - path: "references/知识体系-模块A.md"
    description: |
      【何时查阅】当用户咨询涉及人性分析、动机拆解时
      【内容概要】核心分析框架 + 5种人性模型 + 实战推演模板
      【不读后果】不读此文件直接分析 = 只会输出表面观察，缺少底层模型支撑
      【关键词】人性、动机、分析、推演
 
  - path: "references/场景策略库-领域1.md"
    description: |
      【何时查阅】当用户面对商业谈判、合作博弈场景时
      【内容概要】8种常见商业场景策略 + 决策树 + 话术模板
      【不读后果】不读此文件直接给建议 = 缺少场景化策略，只能给通用建议
      【关键词】商业、谈判、合作、博弈、利益

第三步：在正文里配好场景路由表。

### 场景路由表
 
| 用户咨询类型 | 该查哪个 reference |
|-------------|-------------------|
| 人性分析/动机拆解 | 知识体系-模块A.md |
| 策略设计/攻防推演 | 知识体系-模块B.md |
| 话术设计/沟通技巧 | 知识体系-模块C.md |
| 商业/谈判场景 | 场景策略库-领域1.md |
| 执行/防御场景 | 场景策略库-领域2.md |

拆分效果

| 指标 | Before | After | |------|--------|-------| | 正文行数 | 894 行 | ~450 行 | | 每次加载量 | 31KB | ~17KB（正文 + description） | | Token 节省 | — | 45%-50% | | 回答质量 | 不变 | 不变（甚至更精准） |

正文减少了一半，但 AI 的能力没有缩水。因为那些知识还在——只是从"每次都搬出来"变成了"需要的时候才去拿"。

你的 Skill 需要三层架构吗？

判断标准很简单：

你的 Skill 有 reference 文件吗？
  ├─ 没有 → 不需要（规则全写在正文里就够了）
  └─ 有 → reference 超过 3 个？或单个超过 200 行？
           ├─ 是 → ✅ 必须用三层架构
           └─ 否 → 可选（但写好 description 总没坏处）

检查清单

创建或升级任何包含 reference 的 Skill 时，对照检查：

• [ ] Skill 正文是否包含「资料使用规则」？（指挥棒 1）
• [ ] Skill 正文是否包含「场景路由表」？（指挥棒 2）
• [ ] 每个 reference 的 description 是否包含【何时查阅】？
• [ ] 每个 reference 的 description 是否包含【内容概要】？
• [ ] 每个 reference 的 description 是否包含【不读后果】？（强化指令）
• [ ] reference 文件是否按主题拆分？（不是大杂烩）
• [ ] 文件名是否有辨识度？（不是"参考1.md"）

7 条全勾上，渐进式披露机制才算真正激活。

一句话总结：

Skill 正文是导航图，description 是目录牌，reference 是书架上的书。

AI 先看导航图和目录牌，再按需去书架取书。

不给导航图，它就只能全搬或不搬。

给了导航图，它就能精准找到那本书。

这套方法我已经写进了自己的 Skill 管理工具里，每次创建资料密集型 Skill 时自动走一遍。翻车？再没翻过。