交接文档换了读者:给AI写的入职手册该怎么写

我在准备做 FDE（Forward Deployed Engineer，前线部署工程师，指派到客户现场把 AI（人工智能）真正跑起来的工程师）时，越来越在意一件小事：客户手里的操作手册，是写给人看的。新员工看不懂可以问老同事，AI 看不懂只会照字面猜。

所以我最近在研究一个问题：同一份流程，如果读者从人换成 AI，该怎么写？Anthropic（美国 AI 公司，Claude 大模型的开发方）在介绍 Agent Skills（智能体技能包）时打了个比方：给智能体做一个技能，就像给新员工整理一份入职手册。这个比方让我意识到，交接文档这件老事，正在变成 AI 落地里的一项正式交付物。

背景：Skill 到底是个什么东西

先把概念讲清楚。Agent（智能体，能自己调用工具、分步完成任务的 AI 程序）本身很聪明，但它不知道你公司的规矩。Anthropic 在 2025 年 10 月 16 日的工程博客里介绍了 Agent Skills：它是一个文件夹，里面放着说明、脚本和参考资料，智能体在需要时自己发现并加载。

这个文件夹的核心是一个叫 SKILL.md 的文件（.md 是 Markdown 格式，一种用简单符号排版的纯文本）。文件开头必须有两项元数据（metadata，描述数据的数据）：

• name（名字）：这个技能叫什么；
• description（描述）：它做什么、什么时候该用。

2025 年 12 月 18 日，Anthropic 把 Agent Skills 发布成开放标准，规范放在 agentskills.io 上。按规范，name 最长 64 个字符，只能用小写字母、数字和连字符；description 最长 1024 个字符，要同时写清「做什么」和「什么时候用」。

读者换成 AI，手册结构要跟着变

我读下来，觉得 Skill 设计里最值得 FDE 学的，是 Anthropic 说的 progressive disclosure（渐进式披露，信息按需一层层给，不一次全塞）。它分三层：

• 第一层：所有技能的 name 和 description 在启动时就装进系统提示词（system prompt，开场时给 AI 的总设定），规范估计每个技能约 100 个 token（词元，模型计算文字量的单位）；
• 第二层：AI 判断任务相关时，才把整份 SKILL.md 正文读进来，规范建议正文少于 5000 个 token、不超过 500 行；
• 第三层：正文里引用的附件，比如参考文档、模板、脚本，只在真正用到时才打开。

Anthropic 用 PDF（便携文档格式，常见的电子文档格式）技能举例：填表单的说明单独放在 forms.md（表单说明文件）里，只有要填表时 Claude（Anthropic 的大模型）才去读，平时主文件保持精简。

这跟人看手册的习惯正好相反。人拿到手册会从头翻，AI 的「注意力」是有成本的，每多读一页都占用 context window（上下文窗口，模型一次能记住的内容量）。所以给 AI 写手册，先要想清楚「什么情况下读到哪一层」。

我的观察：最容易被低估的是 description 这一行。Anthropic 明确说，Claude 靠 name 和 description 决定要不要触发这个技能。规范里给的反面例子就是一句「Helps with PDFs（帮忙处理 PDF）」，太空泛。如果描述写成「处理合同」，AI 分不清它该在审合同、起草合同还是归档合同时出场。这一行写不好，后面写得再细也可能根本不会被读到。

一个具体场景：报销审核规则怎么交给 AI

下面是我为了练习设想的示例，不是真实项目。

假设一家公司想让 AI 先过一遍差旅报销单。原来的员工手册里写着：「金额较大的要附说明，特殊情况找财务确认。」老员工看得懂，因为他们知道「较大」大概是多少、「特殊情况」通常指什么。AI 不知道。

如果我进场，会先把这段话拆成 AI 能执行的样子：

• 把「较大」写成数：比如单张发票超过多少元要附说明，这个数要找财务负责人当面确认，不能我自己定；
• 把「特殊情况」列成清单：跨月报销、无发票、外币支付，各自走哪条路；
• 把「找财务确认」写成动作：AI 遇到清单外的情况，停下来、标注原因、转人工，而不是自己猜；
• 把查验发票这种需要每次结果一致的步骤，交给脚本。

最后一条也有出处。Anthropic 在文章里说，有些操作更适合传统代码，比如排序一个列表，用模型逐字生成比直接跑排序算法贵得多；而且很多应用需要只有代码才能给的确定性。PDF 技能里就带了一个 Python（一种编程语言）脚本，专门提取表单字段，Claude 可以直接运行，不用把脚本和 PDF 都读进上下文。

反过来看一个反例：把整本几十页的财务制度原样塞进一个文件交给 AI。按渐进式披露的思路，这样做既浪费上下文，也让 AI 很难在关键时刻找到那一条规定。人能靠目录和经验跳读，AI 每次都要从头消化。

写好之后，怎么知道它真的有用

Anthropic 给出的开发建议里，第一条是 Start with evaluation（从评测开始）：先让智能体跑一批有代表性的任务，观察它在哪里卡住、缺什么上下文，再一点点补技能。另外两条我也记下了：

• 站在 Claude 的角度想：在真实场景里看它怎么用这个技能，留意意外的执行路径，或者过度依赖某段内容；
• 和 Claude 一起迭代：任务做成了，让它把成功做法和常见错误沉淀进技能；跑偏了，让它自己复盘哪里出错。

还有一条安全提醒很适合带进客户现场。Anthropic 说，恶意技能可能带来漏洞，甚至指使 Claude 外传数据，所以只装可信来源的技能；来源不太可信的，用之前要把里面的文件、代码依赖和对外联网的指令都审一遍。

我的观察：这几条放在一起看，手册不再是「写完交付就结束」的文档，而是要跟着 AI 的实际表现持续改的东西。如果我进场，会把「谁负责改这份手册、多久看一次 AI 的执行记录」也写进交付清单，否则客户的流程一变，手册就悄悄过期了。

我的判断

以下是我基于上面材料的判断，不是 Anthropic 的原话：

1. 给 AI 写的手册，会成为 AI 落地的正式交付物。 模型能力大家都能买到，客户自己的规矩只有现场才拿得到。谁能把暗规则写成 AI 读得懂的文件，谁就握住了落地里最难替代的那部分。

2. 写这种手册的核心能力是「拆」，不是「写」。 把「较大」拆成数，把「特殊情况」拆成清单，把「找人确认」拆成动作。这更像需求分析，正是产品经理和 FDE 重叠的地方。

3. 能交给代码的，别交给模型。 需要每次结果一致的步骤用脚本，需要判断的再交给 AI。分不清这条线，项目要么贵，要么不稳。

一个可以照做的建议：挑你团队里一份最常被问的操作文档，只做一件事，给它写一行 description：它解决什么问题、什么时候该用。写不出来，说明这份文档本身的边界就没理清。

留个问题：你们团队的操作手册里，哪一句话是老员工秒懂、AI 一定会误解的？欢迎在评论区写出来。

如果你的团队在推进 AI 落地，卡在规则梳理、数据接入或现场验证上，欢迎留言交流。

我是一个刚入行的 FDE，正在把 AI 落地里的真实约束一篇篇拆清楚。关注下一页科技，一起学。

参考：原文《Equipping agents for the real world with Agent Skills》（Anthropic 工程博客，2025-10-16）https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills

参考：《Specification》（Agent Skills 开放标准）https://agentskills.io/specification