企业官网建设流程全解析

实际使用 AI 编程助手时，最常遇到的问题不是单次提问没答对，而是任务进行到一半，上下文窗口爆了。你刚把一本书、一份几千行的接口文档或者一套团队规范全部塞进对话里，后续请求就开始变慢、变不稳定，甚至出现“已进行多次自动总结，但上下文大小仍超出限制”的提示。book-to-skill 就是针对这个问题出现的一类做法：把资料改造成按需加载的技能，而不是让模型每轮对话都背着整本书工作。标题里提到的“一本书省 51 倍上下文”并不需要当作固定指标，它的价值在于提示一个方向：上下文是可以被管理的资源。下文从上下文工程的角度，把 book-to-skill 的目录结构、技能格式、触发机制、验证方法和排错路径完整拆开讲清楚。

1. 先理解上下文工程：为什么整本书不能直接塞给模型

1.1 上下文窗口是资源，不是无限容器

上下文窗口（context window）指模型在单次推理中能看到的 token 总数。不同模型的上限差异很大，常见的有 60K、200K、1M 等配置。很多人会陷入一个误区：上下文越大越好，只要不超限，资料越全回答越准。

实际并非如此。上下文窗口越大，通常意味着：

• 每轮请求处理的 token 越多，首字延迟和整体耗时上升；
• 费用随 token 数量增长，长会话的成本压力更明显；
• 无关内容混入时，模型需要在大量信息中定位关键片段，注意力可能被稀释；
• 接近上限后，工具会自动触发总结、压缩或截断，结果往往是丢失细节。

所以上下文工程的核心问题不是“能装多少”，而是“哪些 token 该进来、哪些不该进来”。一本书十几万字，一次性放入上下文，等于让模型在每次回答前都先“读完”整本书，但真正用到的可能只有其中几页。

1.2 按需加载：平时只带索引，用到时才翻正文

book-to-skill 的核心思路是“按需加载”。它把一本书或一份大型资料拆成两部分：

• 入口描述：一小段说明，告诉模型这个技能能处理什么问题、什么时候该用它；
• 正文参考：一组小型文件，每个文件只负责一个具体主题，只有在确定需要时才被加载进上下文。

这和我们在真实世界里的做法类似。程序员不会把整本《MySQL 性能调优》放在办公桌上逐字读，而是遇到慢查询时翻索引相关章节，遇到死锁时再看锁机制章节。技能文件就是这些“章节卡片”，SKILL.md 则是封面上的检索词。

这样做的好处是：日常对话中，模型只需要携带技能入口描述；真正命中场景时，再读取对应的参考文件。上下文占用从“整本书”变成“入口描述 + 当前任务相关的一两个小文件”。

1.3 51 倍这个数字应该怎么看待

标题里的“51 倍”来自特定资料、特定任务和特定工具的对比，不是普适结论。节省倍数可以近似用下面这条公式理解：

上下文节省倍数 ≈ 原始整书 token 数 / 技能实际加载 token 数

其中技能实际加载 token 数 = 入口描述 token + 本次任务被触发的参考文件 token。如果一本书有 5 万 token，而某次任务只加载了 1 千 token，倍数就是 50 左右。如果任务需要连续读取十几个参考文件，倍数就会明显下降。

影响节省倍数的因素主要有：

实际落地时，建议不要被“51 倍”绑架，而是先跑通机制，再对自己的资料做一次 token 前后对比，得到属于自己的数据。

2. 环境准备：把 skill 机制跑起来需要哪些条件

2.1 支持 skill 机制的 AI 编程助手

当前主流 AI 编程助手已经陆续支持“技能（skill）”或类似机制。不同产品叫法不同：有的叫 skills，有的叫 commands，有的叫 agents 或 rules。以常见 CLI 助手为例，较新版本通常会在项目目录下预留技能目录，例如.claude/skills/，并在需求命中时自动加载对应技能。

由于各工具版本更新快，落地前先做三件事：

1. 确认当前助手版本是否支持 skill 目录；
2. 确认技能目录的准确路径和命名规范；
3. 确认技能是被动触发还是通过命令手动调用。

不要直接照抄网上的目录路径。先看工具官方文档或本机命令帮助，例如执行assistant --help或查看版本信息，再决定目录结构。这里以常见约定为例，兼容性以你使用的版本为准。

2.2 两种加载方式：自动命中与手动调用

技能通常支持两种加载方式，设计技能时要同时考虑：

推荐做法是：通用且高频的技能靠自动命中，专项且低频的靠手动调用。例如把“数据库慢查询分析”做成自动命中技能，把“公司发布流程”做成手动调用技能，避免模型在日常对话中误读发布相关描述。

2.3 验证环境的最小实验

先创建一个最小技能，验证机制本身是否工作。以常见技能目录约定为例：

mkdir -p .claude/skills/hello-doc/references

在技能目录下创建入口文件 SKILL.md：

--- name: hello-doc description: 当用户提到测试技能、演示技能或者询问技能机制是否可用时使用。 --- # Hello Doc 这是一个最小验证技能。返回一句话说明技能已经加载成功，并列出 references 目录中的文件名。

然后开启一次新会话，输入“测试一下 hello 技能”，观察模型是否读取了该技能。如果模型没有反应，说明目录路径、描述格式或触发机制需要调整。这个最小实验是后续所有工作的基础，不要跳过。

3. 把一本书改造成按需技能：完整操作流程

3.1 先拆分知识结构，不要直接复制原文

拿到一本技术书或一份长文档，先不要急着复制正文。第一步是分析目录和章节，把内容分成三类：

• 判断类：用于决定“现在该做什么”，如故障判断流程、问题分类；
• 操作类：给出具体步骤，如安装、配置、修复；
• 速查类：供查表使用，如参数对照、命令语法、错误码说明。

例如一本 MySQL 性能调优书籍，可以映射成下面的结构：

这个阶段的产出是一张“书籍章节到技能文件”的映射表，它决定了整个技能库的结构，也是后续维护时最容易更新的依据。

3.2 用 SKILL.md 作为技能入口

每个技能目录下必须有一个入口文件，常见命名为 SKILL.md。它由 YAML 前置元信息和正文模板两部分组成。

--- name: mysql-performance-tuning description: 用于 MySQL 慢查询分析、索引选择和参数调优。当用户提到慢 SQL、索引失效、explain 结果解读、数据库卡顿等问题时使用。 --- # MySQL 性能调优 本技能把 MySQL 性能调优资料整理为按需加载的步骤。 ## 使用流程 1. 确认现象：慢 SQL、锁等待、CPU 飙升、磁盘 IO 高。 2. 获取 EXPLAIN 结果，对照 references/explain-reading.md 判断访问类型。 3. 需要选索引时，读取 references/index-selection.md。 4. 修改参数前，先对照 references/config-parameters.md 确认影响范围。 5. 所有变更先在测试库执行，再考虑生产环境。 ## 限制 - 本技能只负责分析和建议，不执行实际变更。 - 涉及生产变更时，需要人工审批后执行。

这里的description是整个技能最关键的部分。它不会完整进入每次对话的使用流程，但模型判断“当前问题要不要触发这个技能”时，主要依据就是它。描述要写清楚三个要素：技能处理什么、什么场景触发、什么场景不触发。

3.3 把正文拆成小型参考文件，每个文件聚焦一件事

references 目录下的文件遵循“一文件一主题”原则。文件不宜过大，理想情况下一个文件几百行以内，控制在一次加载可接受范围。

示例，references/explain-reading.md：

# EXPLAIN 结果速查 ## 关键列含义 | 列名 | 含义 | 常见问题 | | --- | --- | --- | | type | 访问类型 | 出现 ALL 时通常意味着全表扫描 | | key | 实际使用的索引 | NULL 表示未使用索引 | | rows | 预估扫描行数 | rows 越大越需要关注 | | Extra | 附加信息 | Using filesort 需要关注排序开销 | ## 访问类型从好到差 system -> const -> eq_ref -> ref -> range -> index -> ALL ## 常见处理 - type 为 ALL 且条件列适合建索引：优先考虑增加索引。 - Extra 出现 Using temporary：检查 group by 或 order by 是否与索引顺序一致。 - rows 与实际返回行数差距大：关注统计信息是否过期。

文件最后尽量给出“下一步做什么”，这样模型读取文件后能直接产生行动建议，而不是停留在概念解释。

3.4 控制何时把材料带进上下文

拆分完之后，最关键的问题是：技能文件什么时候真正进入上下文。

主流机制有两种实现方式：

• 模型自动读取：当模型判断需要该技能时，把 SKILL.md 以及它引用的 reference 文件读入；
• 用户或工具手动引入：通过命令读取指定文件，再参与后续回答。

无论哪种方式，都要避免一个陷阱：不要在 SKILL.md 正文里贴完整参考文件的内容。SKILL.md 只写流程和指向，正文内容放在 references 下，这样模型平时负担的是“入口 + 流程”，而不是整本书。

一个健康的状态是：日常对话中上下文只增加几百 token，只有当任务命中时，references 里的一两个文件才被加载进来。这样才能真正达到按需加载的目的。

4. 关键设计参数：描述、粒度、触发方式的取舍

4.1 description 质量决定技能能否被命中

description 写得不好，技能机制再完善也不会生效。两种典型写法对比如下：

建议写完 description 后做一个简单测试：从原书疑问中列出 10 个典型问题，分别发给模型，观察技能是否正确触发。触发率低于预期时优先改 description，而不是改代码。

4.2 文件拆分粒度决定上下文成本

拆分粒度直接影响上下文占用：

• 粒度太粗：一个 reference 上千行，触发性地把大量无关内容带入上下文，节省效果大打折扣；
• 粒度太细：文件数量爆炸，模型需要多次读取，检索和加载成本上升，维护负担也重。

推荐以“一次任务需要的最小知识集合”为单位。例如“索引选择”单独成一个文件，“锁与死锁”单独成一个文件，而不是把“性能调优全部内容”放在一个大文件里。

文件拆分完成后，可以做一个简单的 token 估算：

单个 reference token ≈ 文件字符数 / 2（中文场景粗略估算） 一次技能加载 token ≈ SKILL.md token + 所有被读取 reference token

不同模型对中文 token 的切分方式不同，上面只是估算。真正准确的数字需要从工具日志或 token 计数接口获取。

4.3 检索还是固定引用：两种接入方式的取舍

技能文件加载有两种主流接入方式：

小规模技能库（几十个文件以内）建议先用固定引用。等技能数量增长后，再考虑引入检索式选择，并在技能库入口处维护一套文件索引。不要把检索链路一开始就做复杂，先跑通再扩展。

5. 运行验证：如何量化上下文节省，而不是凭感觉

5.1 记录修改前后的 token 消耗

没有数据支撑的“觉得省了很多”没有说服力。验证建议从两条路径取数：

1. 直接观察工具界面显示的 token 消耗；
2. 开启 DEBUG 日志，记录每轮请求的实际 token 数量。

以 DEBUG 日志为例，日志行通常包含 prompt 和 response 的 token 数。记录格式可以简化成：

task_id: task-001 full_book_mode_tokens: 45200 skill_mode_tokens: 1180 saved_tokens: 44020 saved_ratio: 97.4%

建议建立一张对比表：

第三行代表一种边界情况：如果任务要求通读全书内容，技能模式并不比整书模式省多少。这不是失败，而是说明了该任务不适合按需拆分的模式。

5.2 验证技能是否在正确场景被触发

准备一份测试问题集，每个问题标注预期是否触发技能：

这一轮测试能发现两个问题：漏触发和误触发。漏触发时强化 description 中的场景词；误触发时加入“不适用场景”限制。

5.3 从工具日志和会话记录中确认加载链路

如果技能被触发但结果不对，需要确认模型到底读取了哪些文件。此时要从三个层面检查：

• 会话输出中是否出现技能加载提示；
• DEBUG 日志中是否出现了 references 下文件的读取记录；
• 模型回答中引用的内容是否来自技能文件。

一般排查链路是：先确认技能是否被触发，再确认文件是否被读取，最后确认读取的文件内容是否正确。不要跳过第二步直接改 prompt。

6. 常见问题排查：技能不触发、上下文还是爆、答案反而变差

6.1 技能没有被触发

现象：输入了明显和技能相关的问题，模型却像没看到技能一样回答。

可能原因：

• 技能目录路径不对，助手没有扫描到；
• SKILL.md 的 frontmatter 格式不正确；
• 开启会话时没有重新加载技能配置；
• 新会话才开始生效，当前会话仍是旧配置。

检查方式：先确认技能文件存在于正确目录，再开启新会话测试。如果仍不触发，把 description 改成更明确的场景词，例如把“数据库问题”改成“慢 SQL、索引失效、EXPLAIN 结果解读”。

6.2 上下文仍然超限

现象：即使使用了 skill，仍然出现“已进行多次自动总结但上下文大小仍超出限制”或类似报错。

排查顺序：

1. 检查 SKILL.md 中是否复制了整段原文；
2. 检查 references 文件是否过大，一次性被全部加载；
3. 检查会话历史本身过长，与技能无关；
4. 检查是否有 MCP 服务器或其他工具在每轮请求中注入大量内容。

处理建议：把大 reference 继续拆小；明确 SKILL.md 中“只读取当前任务相关文件”；必要时候手动调用技能而不是依赖自动命中；如果长会话本身是问题，优先考虑任务分段，而不是把所有步骤放在一个会话里。

6.3 用技能后回答质量下降

现象：上下文省了，但回答明显不如直接粘贴原文时准确。

可能原因：

• 参考文件丢失了关键上下文或示例；
• 拆分的文件之间缺少衔接，模型只读了其中一个；
• SKILL.md 中缺少使用顺序，模型不知道该先读哪个文件。

处理建议：在每个 reference 文件开头加“本篇解决什么问题、前置文件是什么、下一篇是什么”；在 SKILL.md 中明确读取顺序和判断条件。质量优先于节省，先保证回答可用，再优化 token 消耗。

6.4 排查顺序表

这套顺序的核心逻辑永远是：先确认输入是否正确，再检查路径和配置，最后才怀疑工具本身。

7. 最佳实践与扩展方向：从一本书到一套知识库

7.1 可复用的技能拆分清单

每次新建技能前，按下面这份清单检查：

• [ ] 明确技能一句话职责：解决什么问题，不解决什么问题；
• [ ] 完成章节到文件映射表，确认没有遗漏关键主题；
• [ ] SKILL.md 的 description 包含触发场景词和不适用场景；
• [ ] 每个 reference 文件只聚焦一个主题，保持适度长度；
• [ ] SKILL.md 中只写流程和文件指引，不贴大段原文；
• [ ] 明确加载方式：自动命中还是手动调用；
• [ ] 准备 5 到 10 个测试问题，覆盖触发、不触发、边界场景；
• [ ] 记录整书模式和技能模式的 token 消耗；
• [ ] 确认回答质量不低于直接粘贴原文的水平。

这份清单同时适用于技能库的代码审查和新人培训。每次技能变更后，至少跑一遍测试问题集再提交。

7.2 学习环境与生产环境的差异

本地个人项目里，把技能目录放在项目下，验证机制、改描述、拆文件都很快。生产环境则要考虑更多：

不要把学习环境里的随意改法直接带到生产。尤其要注意：生产环境中的技能文件可能包含团队内部规范或敏感信息，权限控制和内容审核不能省略。

7.3 下一步扩展：从单技能到技能库

当技能数量增长到几十个以上，维护方式要从“单个技能”升级为“技能库”：

• 统一目录规范：所有技能使用一致的结构和命名；
• 建立索引文件：在技能库入口维护一份技能清单，说明每个技能的适用范围，降低检索成本；
• 引入自动评测：把测试问题集固化成脚本，每次技能变更自动回归；
• 设计更新机制：书改版后，技能文件需要同步更新，避免旧信息继续误导模型；
• 控制每次加载范围：技能库再大，每次进入上下文的仍然只是入口描述和命中文件，这是整个机制的底线。

还有一个容易被忽略的方向：把“对话历史中的重复知识”沉淀成技能。比如同一个团队频繁讨论同一份部署流程，就可以把这份流程抽成技能文件，下次新会话直接调用，解决“新开会话丢失上下文记忆”的痛点。这比每次重讲一遍更可靠。

回到最初的问题：一本书省 51 倍上下文并不是一个必须达成的指标，而是一个验证方向。book-to-skill 的价值在于它把“堆资料”变成了“建索引、拆内容、按需加载”的工程过程。新手建议先拿一份自己最熟悉的技术文档，按第 3 节的操作流程完整做一遍，记录修改前后的 token 数和回答质量。完成一次全流程之后，再考虑扩大技能库、引入评测和自动化。掌握这套上下文管理思路后，无论换哪个编程助手、哪种模型，你都能在有限上下文窗口内做出更可控、更稳定的 AI 辅助工作流。