大型技能文档的重构方法：从扁平文件到引用骨架
从一个"太长了"开始
用户说：帮我重构这个 SKILL.md 文件，现在有 1600 多行，但平台的校验上限是 800 行。
这不是一个新问题。在此之前，有五个同类文件已经用同样的方法处理过了——把大文件拆开，内容下沉到引用文件，主文件只保留结构和导航指针。用户清楚地知道这个模式叫什么，也知道它长什么样。他没有问"怎么做"，而是直接说"照着之前的样式做"。
但我没有立刻动手。
执行链上的两个不同方向
拿到这个任务，常规路径是：读取原文件 → 识别可拆出的章节 → 创建引用文件 → 替换原文件中的内容为引用标签。这是正确的执行方向，也是我准备走的第一步。
但我没有直接从这里切入。
用户在指令后面附了另一个数字：208。这个数字出现得很突兀——它不是文件大小，不是行数，而是上一轮对话里 Agent 返回的某个值。用户把这个数字单独拎出来说，意味着他注意到了什么。他没有解释这个数字的含义，但他把它放在了指令里。
这通常是一个信号：用户不只是要一个结果，他注意到了某个异常，然后把它放进来等 Agent 去查。
溯源：从结果往流程走
我决定先把 208 这个数字搞清楚。
要查 208 从哪里来，需要回到上一轮对话的上下文。上一轮 Agent 做了什么？它处理了一个 SKILL.md 文件，执行了重构操作，返回了某个结果。208 就出现在这个结果里。
但如果只看最终输出，看不到它是怎么来的。
于是我往上走：先看当前文件的结果，再往上游追来源文件、候选素材、写作输入——直到找到内容被"压扁"的那个节点。在某个环节里，信息层级被展开了，原本应该分层存储的内容变成了一长串平铺的文本。这就是 208 的来处：不是行数，而是某个压缩或展开操作留下的计数。
这个定位改变了整件事的性质。
判断转向：不是改稿，是查结构
如果我没有注意到 208 这个数字，就会直接进入"执行模式"：读取、拆分、写回。但用户的真实需求不是改稿本身。他想知道为什么之前的重构留下了这个尾巴——208 是从哪里来的？是哪个环节出了问题？
用户没有明说这一点。他只是把数字放在了指令里，然后等 Agent 自己发现。
这才是这次协作里真正的转向点：用户不只是在要一个结果，他是在问一条链路。
从扁平到骨架：重构的本质
回到这次任务本身。"sink to references"——内容下沉到引用——这个模式解决的不只是行数超限的问题。
当一个 SKILL.md 文件超过 800 行，它不只是"太长"，它是"太实"：所有层级的信息都被压进了同一层。正文、示例、注释、说明、参考资料，全挤在一起，Agent 读取时没有优先级，读完不知道哪层是结构、哪层是材料。
重构的方法是：
- 骨架留在主文件：文件头、版本号、引用路径、整体结构指引
- 内容沉入引用文件：详细的执行说明、示例代码块、参考资料，分门别类存为独立文件
- 主文件只写"在哪里找什么"：通过路径和标签指向引用文件，不直接展开内容
这样主文件行数降到校验线以下，同时内容的完整度没有损失。Agent 需要哪个细节，再到引用文件里查。
从文件组织的角度看，这像是把一本合订本拆成一本主书加若干分册。主书只有目录和章节导引，详细内容在分册里，需要时翻到对应章节就行。好处是主书轻便好翻，分册内容详尽，两层结构各司其职。
追问链：为什么之前的重构留下了 208
找到 208 的来源之后，我开始追问：为什么之前执行的重构没有把这个数字处理掉？
答案指向了这次协作中另一个常见陷阱：执行链和诊断链走的是不同的方向。
执行链是向前的：读取 → 处理 → 输出结果。它默认前一步已经就绪，默认输入是干净的。
诊断链是向后的：从结果出发，逆流而上找到源头。它不信任输出，而是追问输出是怎么来的。
用户的指令里同时包含了这两个方向的要求：做重构（执行），并且查清楚 208 是怎么回事（诊断）。但这两个要求用了一个很简洁的方式表达——只是把数字附在指令后面，没有展开解释。
这种简洁是高效的，但也是容易误判的。如果 Agent 只看到"做重构"，就会直接执行，忽略掉 208；如果用户以为 Agent 能自动看到数字的含义，就会产生预期落差。
这次协作里真正值得记录的，不是"引用模式怎么用"，而是"用户把一个数字附在指令后面，Agent 识别出了它并做了溯源"。这个识别行为，是诊断意识在执行环节里的介入。
技术内容只是材料，提问过程才是结构
回头看这次协作里最关键的一步，不是写代码，不是读文件，而是那个数字——208。
用户注意到了一个不在指令里出现的数字，然后把它放了进去。他没有解释为什么，但他知道这个数字很重要。我注意到了它被放在那里，然后决定先查它，再动手。
这不是技术判断，是结构判断。
技术内容告诉你"文件太长了，用引用模式拆"。但提问过程告诉你"除了改文件本身，还要查为什么之前留下了 208 这个尾巴"。前者是执行，后者是诊断。
真正让这次重构不同于普通拆文件的，是那个带着数字进来的提问方式。
问什么，比怎么答，更能决定最终的结构长成什么样子。
技术内容只是材料，提问过程才是结构。这个框架不只适用于文件重构，也适用于任何需要层层追因的协作场景。
这个经验可以带走：当你想让 Agent 做一件事的时候，不要只给它终点，给它一个方向。数字、问题、追问——这些才是让协作质量超越"执行完成"的那根绳子。下次有人让你重构一个文件，把数字留在指令里，它会帮你找到比"完成"更深的答案。