这是「近五年 AI 技术演进」系列深挖的第九篇。上一篇 A2A 解决的是「Agent 之间怎么互相派活」；这一篇回到单个 Agent 内部，解决一个更朴素的问题：那些你反复交代的专业方法，能不能只写一次。一句话定位：用文件夹封装的领域专业知识。全文约 5800 字，含一份可直接落地的 SKILL.md 完整示例、一张四概念对比表和六张原创信息图。

一、痛点：同一份经验，你写了第七遍

先看三个真实场景。

场景一。你让 AI 写周报。第一次它写得像流水账，你补了一段要求：「先结论后过程，数字要带环比，风险要写清影响面和责任人，别超过 400 字。」第二次换了个对话，它又写成了流水账，你只能把那一段再贴一遍。第三次、第四次……半年下来，这段要求你复制粘贴了四十多次，而且每次版本都略有不同——有一次漏了「责任人」，有一次加了「不要用『持续推进』这种空话」。

场景二。你们团队审合同有一套固定动作：先看主体资质，再看付款节点与验收标准的对应关系，再看违约责任是否对等，最后核一遍争议解决条款和管辖地。这套动作是法务总监花了三年总结出来的，写在一次内部分享的 PPT 里，之后再没人打开过。现在你想让 AI 帮忙初审合同，只能在 prompt 里凭记忆复述一遍——每次都漏掉一两步。

场景三。你要把一份技术方案转成 PPT。你知道该用什么版式、图表怎么配色、每页留多少字。这些「知道」没法写进一句话的指令里，于是你每次都手动调整，AI 每次都在猜。

三个场景，同一个病灶：你有一份稳定的专业方法，但它没有地方存放。

大多数人会用三种办法应付，三种都会失败：

第一种，复制粘贴。短期有效，长期必然漂移。同一套方法在你的聊天记录里存在十几个版本，没有哪个是权威版本，也没人知道最新版是哪一版。更要命的是，它只存在于你个人的输入框里——同事拿不到，下次换个工具也用不上。

第二种，全部塞进系统提示。这是团队最常干的事：把《写作规范》《审稿清单》《周报模板》统统拼进 system prompt。能跑，但代价是每一轮对话都要重发一遍这几千字，成本线性上涨；更隐蔽的代价是注意力稀释——上下文里塞了二十条规则，模型真正遵守的往往只有最前面和最后面那几条。

第三种，丢进知识库让 RAG 检索。这里有个根本性的错配：RAG 擅长找「事实」，不擅长找「流程」。你问「我们的付款节点是怎么规定的」，它能检索到；但「审合同的正确顺序是什么」，这是一个过程，不是一段文字，向量检索召回的是「最相似的段落」，不是「该走的下一步」。而且检索是概率性的：同一份知识，这次召回了，下次可能没召回。流程不能靠碰运气。

问题的根子在于，我们一直把「知识」当成一种东西，其实它至少分三层：

第一层和第三层都有人管，中间那层长期是空白。Skill 填的就是这个空。

二、Skill 的本质：一个文件夹，就是一份岗位说明书

2025 年 10 月 16 日，Anthropic 随 Claude 发布 Agent Skills。两个月后的12 月 18 日，它被开放为跨平台标准（agentskills.io），三十多个工具陆续跟进——Cursor、VS Code、GitHub Copilot、各种 Agent 框架。一个新概念能在两个月内变成行业格式，原因不复杂：它的实现简单到几乎没有实现。

一个 Skill 就是一个目录：

就这么四类东西，而且只有第一类是必需的：

• SKILL.md：唯一的必需文件。开头是一小段 YAML frontmatter（name+description），后面是给模型看的正文指令；
• references/：放长尾资料。写作规范全文、字段字典、API 手册、案例库——那些「模型偶尔需要看一眼」的东西；
• scripts/：放可执行代码。字数统计、格式转换、批量改名、渲染图表；
• assets/：放静态资源。模板文件、字体、示例文档。

没有 API，没有服务端，没有需要注册的账号。它是一个目录，你可以git clone它，可以打包成 zip 发给同事，可以像代码一样做 code review。

我更喜欢这个类比：Skill 是一份岗位说明书，不是一次工作交代。

你跟新员工说「帮我把这份周报改一下」，这是 Prompt——这一次的交代。你递给他一本《本部门周报规范》，这是 Skill——这个岗位的说明书。前者每次都要说，后者说一次就够，而且能传给下一个人。

这个类比还能解释很多细节。为什么岗位说明书要写「什么情况下适用、什么情况下不适用」？因为新员工最怕的不是不会做，是在不该用这套方法的地方硬套。为什么说明书后面要附表单模板？因为模板比文字描述更难被误解。

三、渐进式披露：整个设计最聪明的地方

如果 Skill 只是「把 prompt 存成文件」，它不值一提。真正让它成立的是一个机制：渐进式披露（Progressive Disclosure）。

先说约束。假设你给 Agent 挂了 50 个技能，每个技能的完整说明平均 2000 token。全量注入就是 10 万 token——还没开始干活，窗口就满了，而且每一轮都要重发。这条路直接死掉。

渐进式披露的做法是：把「知道有这本书」和「读这本书」拆开。

三层，每层的成本差一个数量级：

第一层，常驻的只有目录。系统提示里注入的不是技能全文，而是每个技能的name+description，大约 50~100 token。50 个技能，常驻成本 3000~5000 token，相当于多贴了两页文档。这一层回答的问题是：「有哪些技能存在，各自管什么」。

第二层，命中后才读全文。模型判断当前任务和某个技能的描述匹配，才去读完整的SKILL.md。这一层通常 800~3000 token。它回答的是：「这类活具体分几步，每步做什么，哪里有坑」。

第三层，需要细节时才展开。SKILL.md里写着「格式细节见references/style-guide.md」，模型读到这一句、且确实需要时，才去打开那一个文件。这一层可以很大——一份完整的品牌规范可能两万 token——但一次任务通常只展开一两个。

关键在于，这三层不是「为了省 token 的妥协」，而是符合专业工作的真实节奏。一个资深编辑改稿时，脑子里常驻的也不是全部规范，而是「我们有排版规范、有术语表、有敏感词清单」这三条目录；真改到标点那一段，才去翻标点规范。

所以准确的说法不是「省了 90% 的 token」，而是：上下文是稀缺资源，但比上下文更稀缺的是模型的注意力。塞进去不等于用得上。把 50 份文档全塞给模型，它的表现往往不如只塞 3 份——这就是长上下文里著名的「中间遗忘」。

三层机制的成本结构，值得单独列一张表：

为什么它不需要向量库

这里有个常被问到的问题：Skill 和 RAG 到底是什么关系？

一句话：RAG 是「猜哪一段相关」，Skill 是「按目录翻书」。

RAG 的检索是一次相似度计算，召回的段落由向量决定，你无法保证它一定召回第二步而不是第五步。Skill 的检索是一次路径查找：模型看到references/style-guide.md这个文件名，决定打开它，路径是你写在正文里的，范围是确定的。

这个差别在工程上非常实际：

• RAG 的失败是静默的——没召回，模型就用它自己的常识编，你不会收到任何报错；
• Skill 的失败是可见的——文件不存在、路径写错、脚本报错，都能当场发现。

所以这两者不是替代关系，而是分工：事实类知识仍然该进 RAG（量大、更新频繁、按相似度召回是合理的）；方法论、流程、规范该写成 Skill（量小、结构稳定、必须确定性命中）。一份 300 页的产品手册放 RAG，一份「怎么审这份合同」放 Skill，各就各位。

四、手写一个 SKILL.md

理论讲完，动手。下面这份是我自己天天在用的一个技能，写技术文章用的——正好这篇文章就是它跑出来的。文件放在~/.claude/skills/tech-article-writer/SKILL.md：

--- name: tech-article-writer description: 写技术长文时使用。当用户要求撰写、改写或排版技术文章， 或需要把零散素材整理成一篇可发布的长文时使用。不用于：短文案、 产品介绍、新闻稿、纯翻译任务。 --- # 技术文章写作 面向工程师读者的技术长文。目标是「读完能上手」，不是「读完觉得厉害」。 ## 1 适用与不适用 适用：3000 字以上的技术解析、原理拆解、方案对比、踩坑复盘。 不适用：一句话文案、发布会通稿、纯 API 文档、需要营销话术的场景。 不确定时，先问用户目标读者是谁——读者决定深度。 ## 2 五步流程 ### 2.1 定位（产出：一句话定位 + 所属层级） 用一句话说清这篇文章在技术栈里的位置，格式为： 「用 X 封装的 Y」。定位不清就不要开始写。 ### 2.2 找痛点（产出：三个具体场景） 至少三个真实场景，每个场景要有具体动作和具体失败后果。 禁止使用「效率低下」「体验不佳」这类没有画面的词。 ### 2.3 拆机制（产出：分层的结构图说明） 先讲机制再讲用法。凡是能用图说清的，不要用段落堆。 每个机制必须回答：它解决了什么约束？不这么做会怎样？ ### 2.4 写代码或配置（产出：可直接运行的示例） 示例必须是真实可用的，不要伪代码。示例后面逐段解释「这行为什么这么写」。 ### 2.5 收口（产出：判断标准 + 行动建议） 结尾给读者一个可执行的下一步，不给空洞的展望。 ## 3 硬约束 - 全文 3000~6000 字，超出则拆篇，不压缩深度。 - 每 800 字内必须出现一个小标题、列表、表格或图，纯文字段落不超过 5 行。 - 禁用词：赋能、抓手、闭环、生态位、降维打击、颠覆。 - 每个技术判断后面必须跟一句「为什么」，不允许只给结论。 - 引用他人观点必须注明来源与时间，不确定的宁可不写。 - 中文与英文、数字之间加空格；使用中文全角标点。 ## 4 结构模板 导语（150 字内，说清「这篇解决什么问题」） → 痛点（三个场景） → 定义与时间线（一段话说清是什么、什么时候出现） → 机制拆解（本文核心，占 40% 篇幅） → 完整示例（代码或配置，逐段解释） → 对比表格（与相邻概念划清边界） → 判断标准（什么时候该用、什么时候不该用） → 收口 ## 5 交付前检查清单 逐条自查，任何一条不通过就回到对应章节改： - [ ] 开头 150 字内说清了这篇文章解决什么问题 - [ ] 至少有 3 个具体场景，每个都有具体动作和后果 - [ ] 核心机制有图，且图能独立看懂 - [ ] 代码示例可运行，没有伪代码 - [ ] 有一张对比表格，边界划清了 - [ ] 全文没有出现禁用词 - [ ] 每个判断后面都有「为什么」 - [ ] 字数在 3000~6000 之间 ## 6 参考文件 - 排版与标点细节：见 `references/style-guide.md` - 十种常见的开篇结构：见 `references/outline-patterns.md` - 交付前逐条核对：见 `references/review-checklist.md` ## 7 常见错误 1. **先写定义再写痛点**——读者不知道这东西解决什么问题，定义就是废话。 2. **把「是什么」写了两千字，「为什么」只有两句**——深度在为什么里。 3. **示例是伪代码**——读者跑不起来，等于没给。 4. **对比表格只列优点**——不列缺点和适用边界，读者无法做决策。

这份文件一百来行，逐段拆开看，每一段都有明确职责。

frontmatter：唯一进入上下文的部分

name: tech-article-writer description: 写技术长文时使用。当用户要求撰写、改写或排版技术文章， 或需要把零散素材整理成可发布的长文时使用。不用于：短文案、 产品介绍、新闻稿、纯翻译任务。

三个硬规则，都来自规范：

• name最多 64 字符，只能用小写字母、数字和连字符，而且必须和目录名完全一致。写成TechArticleWriter或者目录叫tech_writer而 name 叫别的，都会加载失败。
• description最多 1024 字符，非空，不能包含 XML 标签。它是模型判断「要不要用这个技能」的唯一依据。
• 描述必须同时回答两个问题：做什么、什么时候用。官方文档的说法是，如果只写「帮助处理文档」，模型和听到「你负责帮忙搞文档」的新员工一样茫然。

还有一个容易忽略的点：用第三人称写，不要写「我可以帮你……」。这段文字是被注入到系统提示里的，第一人称会让模型的角色认知产生偏移。写「写技术长文时使用」，不写「我能帮你写技术长文」。

正文：流程写「产出物」，不写「要做好」

看第 2 节。每一步后面都跟着一个括号：（产出：一句话定位 + 所属层级）。

这不是装饰。「做好」不可判定，「产出这个」可判定。一个没有产出物的步骤，模型会用一段漂亮的话糊过去，然后进入下一步；有了产出物，它必须交出具体东西，交不出来就说明这一步没做。

同样重要的是第 2.2 节里那句「禁止使用『效率低下』这类没有画面的词」。这条约束的成本是十五个字，收益是把「写得空」这个最常见的失败模式直接堵死。好的 Skill 正文，一半篇幅在写「不要什么」。

硬约束：必须可判定

「写得专业一点」不是约束，是愿望。「禁用词：赋能、抓手、闭环」是约束——可以用程序检查对错。

判断一条约束合不合格，只需问一句：能不能写出一个脚本，一跑就知道过没过？能，就是硬约束；不能，就还是回到「品味」层面，需要靠检查清单和示例来引导。

检查清单：最便宜的提质量手段

第 5 节那八条 checkbox，是整份文件里性价比最高的部分。

原因很简单：模型在生成时是逐字往前走的，它看不见自己刚写完的全局；但当你让它「回头检查」时，它是在读一份完整的稿子。这两个动作的认知负荷完全不同。加一段检查清单，往往比在上文加三条要求更有效。

参考文件：在用到的那一步指路

注意第 6 节的位置——它在正文末尾，但每一行都写明了「什么时候该看」：「排版与标点细节」「十种常见的开篇结构」。

更好的写法是把引用嵌进对应的步骤里。比如在 2.2 节写「需要更多开篇结构参考时，读references/outline-patterns.md」。因为模型是顺序读的，读到第三层的时候，它已经忘了文末还提过一个文件。引用离使用点越近，被真正打开的概率越高。

五、和 Prompt / Tool / MCP 划清边界

这四个词现在被混用得厉害，必须摊开讲。

用一句话把四者串起来：

Prompt 说「这一次」，Skill 说「这一类」，MCP 说「怎么连」，Tool 说「能做什么」。

再补一句更本质的：Tool 给的是「能力」，Skill 给的是「知识和方法」。你给了 AI 一把电钻（Tool），它知道怎么转（能力）；但你没给它《本工地打孔规范》（Skill），它会在承重墙上打。

这个区分解释了为什么 Skill 出现得这么晚。2023 年大家在解决「模型能不能调用工具」，2024 年在解决「工具怎么标准化接入」，直到工具和连接都不再是瓶颈，才发现真正的瓶颈是——工具有了，可它不知道我们这行是怎么干活的。

六、Skill 里为什么可以带脚本

这是 Skill 和「一份写得比较长的 prompt」最实质的区别。

先看一个具体的失败。你让模型统计刚写完的这篇文章有多少字。它会给你一个数字，而且说得很自信。这个数字大概率是错的——模型不擅长精确计数，它是在估算 token 分布，不是在数字符。

现在scripts/check_length.py里放十行代码：

import re, sys, pathlib text = pathlib.Path(sys.argv[1]).read_text(encoding="utf-8") text = re.sub(r"```.*?```", "", text, flags=re.S) # 去掉代码块 cn = len(re.findall(r"[\u4e00-\u9fa5]", text)) # 汉字数 en = len(re.findall(r"[A-Za-z]+", text)) # 英文词数 print(f"汉字 {cn} 个，英文 {en} 词，合计约 {cn + en} 字")

SKILL.md里只要写一句「交付前运行python scripts/check_length.py <文件>核对字数」，这个数字就永远准确。

这里有双重收益，第二重经常被忽略：

第一重，可靠性。把「有唯一正确答案」的步骤交给代码，模型就不再需要猜。

第二重，token。脚本的源码不会进入上下文——模型只是执行它，拿回 stdout。一个两千行的转换脚本，对上下文的成本就是一行输出。这是渐进式披露在「代码」这个维度上的延伸：连代码本身都可以不读。

哪些事该写成脚本，判断标准只有一条：

这一步有没有唯一正确答案？

有，就写成脚本：字数统计、格式转换（Markdown → HTML）、Excel 公式计算、图片压缩、SVG 渲染 PNG、批量重命名、文件校验、固定格式的报表生成。

没有，就留给模型：判断这段论证有没有说服力、这段代码的意图是什么、这个方案在什么场景下不适用。这些事写不出 if-else。

顺手说一个反面：别把 Skill 写成「传统程序 + 一个多余的 LLM」。有些团队把全部业务逻辑塞进脚本，SKILL.md 只剩一句「运行 main.py」，那这个 Skill 就退化成了一个 CLI 工具，模型变成了一个不太可靠的路由器。脚本应该只承担那些「确定性环节」，判断、取舍、表达，仍然留给模型。

还有一条安全提醒，值得单独写一段：Skill 能带脚本，意味着安装一个 Skill 等于安装一份可以执行的代码。官方文档对此说得很直接——恶意 Skill 可以引导模型调用不该调用的工具、访问不该访问的数据。所以：只装自己写的和可信来源的；装之前把scripts/里的代码读一遍，特别注意有没有意料之外的网络请求。把 Skill 当软件对待，而不是当文档对待。

七、什么时候该写：三次法则与三道关

不是所有重复劳动都值得封装。我的判断起点是一个很土的经验法则：同一套流程，你在不同对话里重写第三次，就该沉淀了。

第一次是探索，第二次是验证，第三次说明它是稳定需求——不是偶然，而是你的工作里反复出现的一类任务。

但「重复」只是必要条件，还要过三道关：

第一关，步骤是固定的，顺序有意义。换了顺序就出错，说明这是流程而不是资料。反过来，如果只是「需要知道这些信息」，那它该进文档库或 RAG。

第二关，有可判定的硬约束。字数、格式、口径、禁用词、必须引用的字段——这些能当场验证对错。如果一个技能里全是「要专业」「要有洞察」这类没法验证的话，它更接近一份 prompt 模板。

第三关，有确定性环节。有计算、转换、渲染，才需要脚本。没有的话，一份纯SKILL.md也完全够用——先别写脚本，脚本是维护成本最高的一部分。

三道关都过，才值得投入一个下午。

反过来，三种东西不要急着封装：

一次性任务。「帮我把这个 CSV 转一下」——写个 prompt 就完了，为它建目录、写文档、维护版本，是纯粹的浪费。

个人偏好。「我喜欢用短句」——这属于 prompt 或AGENTS.md的范畴，不值得做成一个技能。

还没跑通的流程。这条最容易被忽略。Skill 会把你的流程固化下来，包括里面的错误。一个没验证过的方法，封装之后会被稳定地、可复现地执行错。先手工跑通三遍，再封装。

八、组织多个 Skill：命名、粒度与描述冲突

一个技能好用，十个技能就开始互相打架。这部分的经验，基本都是从「选错技能」的故障里长出来的。

命名：让目录自己会说话

name只能是 64 字符以内的小写字母、数字、连字符，且必须和目录同名。在这个约束下，推荐两种命名法：

• 动宾式：writing-weekly-report、reviewing-contract、converting-markdown
• 领域式（有明确归属时）：docx、pptx、xlsx、pdf

技能多了以后，用目录做一层分区：skills/docs/、skills/data/、skills/growth/。平铺五十个目录，人和模型都不好找。

粒度：一个 Skill 对应一个交付物

判断粒度有个简单标准：这个技能能不能用一句话说清「交付什么」？

• 「审合同」——能，交付一份带风险标注的审查意见。合适。
• 「法务」——不能，交付物不明确。太宽。
• 「检查合同第 7.2 条的违约责任表述」——能，但太窄，一辈子用不上几次。太细。

太宽的技能会变成万能垃圾桶，什么都往里塞，最后描述写得含糊，谁都选不中它。太细的技能会让技能数量爆炸，而技能数量和选错率是正相关的——这和工具多了会选错工具是同一个道理。

一个经验值：一次任务命中 2~3 个技能是正常的（比如「写周报」命中了周报技能 + 数据查询技能）；如果经常命中 5 个以上，说明你的粒度切碎了，该合并。

描述冲突：九成的选错错在这一行

假设你挂了三个技能，描述分别写着：「处理文档」「处理各类文档内容」「文档相关的写作与排版」。

结果一定是随机命中。因为从描述层面看，它们没有区别。

写法上的三条纪律：

第一，动词开头，说清交付物。「审合同」比「合同相关」好，「把合同逐条标出风险点」比「审合同」更好。

第二，写「不用于什么」。这是最被低估的一句。上面那个tech-article-writer的描述末尾写着「不用于：短文案、产品介绍、新闻稿、纯翻译任务」——这二十来个字，把最容易误触发的四类任务挡在门外。否定式边界比肯定式功能更能提高准确率。

第三，放进区分性关键词。同一批技能之间，一定有某个词能把它们分开：文件类型（.docx/.pdf）、动作（提取 / 生成 / 校对）、交付物（表格 / 演示 / 长文）。把这些词写进描述，而不是写「各类」「多种」「相关」。

建一个触发测试集

最后一条，也是最少人做的一条：给你的技能写一个二十条的触发测试集。

十条「应该触发」的（用你平时真实的说法，别用规范化的说法），十条「不该触发」的（尤其是那些看起来像、其实不该用的）。

每次改完描述，把这二十条跑一遍，看命中率。这件事花二十分钟，能省掉后面几个月的「怎么又不听话了」。

技能库和代码库一样，是有维护成本的。一份过期的手册，比没有手册更危险——因为模型会严格执行它。

九、写在最后

回头看这条演进线，会发现它一直在解决「AI 与世界之间的接口」，只是接口的层次在往上走：

• Tool / Function Calling（2023）解决了「AI 能不能动手」；
• MCP（2024）解决了「工具怎么标准化接入」；
• A2A（2025）解决了「Agent 之间怎么协作」；
• Skill（2025）解决了一个更软、也更难的问题：「我们这行是怎么干活的，怎么交给它」。

前三层都是协议，是硬的东西，谁都能写出来。第四层不是协议，是经验。这也解释了为什么 Skill 的标准只有薄薄一页——它刻意不规定内容，因为内容才是门槛。

对开发者的影响也很直接：过去做 AI 应用，难的是把模型接进系统；现在这一步正在变成标准动作（一个 MCP Server、一个 SDK 调用）。真正拉开差距的，变成了你手里有没有值得封装的经验——那套审合同的顺序、那份周报的口径、那个写了三年的检查清单。

所以我的建议不是「去学怎么写 Skill」。语法半小时就能学完。建议是：翻一翻你过去半年的聊天记录，找出那段你复制粘贴次数最多的要求。把它写成一个SKILL.md，跑一遍，再改一遍。

第一个技能通常很粗糙，但它会让你开始用另一种眼光看自己的工作：哪些动作是每次都在重复的判断，哪些只是这一次的临时交代。

这个区分一旦建立起来，你就不太会再问「怎么让 AI 更懂我」了——你会直接去写下来。

参考资料：Anthropic 官方文档（Agent Skills 概览 / Skills API 指南 / 创建自定义技能）、Agent Skills 开放标准规范（agentskills.io）、Claude Academy《Introduction to Agent Skills》、Anthropic 工程博客（Code Execution with MCP, 2025-11）。文中 token 量级为写作时的实测估算，会随模型与实现变化。