Agent Skill 完全指南：从 SKILL.md 到渐进式披露，告别上下文混乱

Agents 的能力这两年卷得很厉害但我发现很多人对Agent Skill的理解还停留在给 Prompt 加个文件的层面。我最近在调一个 agent 项目时把一份几十页的产品手册直接塞进系统提示词结果上下文窗口被吃干抹净回答问题时经常把 A 模块的规则套到 B 模块上后来换成SKILL.md的方式按技能包拆开、按需加载同样的模型瞬间就靠谱多了。这篇文章我想把 Skill 这东西从头讲透SKILL.md 到底是什么、渐进式披露Progressive Disclosure是怎么工作的、它和 Agent / 工具MCP的边界在哪最后分享一批我实测过、真正能提升效率的 Skill 清单。无论你是刚开始接触 Agent 开发的小白还是已经被 Prompt 工程折磨过一阵子的老手这篇都能给你一套可落地的参考。1. 为什么需要 Skill从临时提示词到可复用的技能包1.1 先还原一个我踩过的坑上个月我在做一个内部文档问答 Agent最开始的方案非常朴素把所有产品操作手册、FAQ、历史故障记录全部拼进 System Prompt觉得信息给的越多模型回答越准。结果上线后状况百出——上下文被塞满模型不仅越来越健忘还经常把不同业务的规则混在一起回答。最典型的一次用户问退款流程模型居然引用了发票开具章节里的操作步骤。后来我把手册拆成了十几个功能模块每个模块对应一个 Skill 目录目录里写清楚适用场景和使用步骤。改造之后模型表现立刻稳定了很多。这件事让我意识到一个关键问题给 Agent 喂信息的方式比信息本身更重要。你一股脑塞给它的信息它根本不知道什么时候该用哪一部分但当成技能包挂载后它自己会判断当前问题激活哪个技能。1.2 Skill 要解决的是知识复用和注意力的按需分配如果你写过大模型应用应该能感受到一个矛盾既能给模型无限的背景知识又希望它把有限的上下文窗口花在刀刃上。Skill 本质上是一套知识打包 按需加载的工程方案。我用一个生活化的类比来解释。你面前放着一本 800 页的菜谱你找红烧肉的做法时不会把整本书背下来而是先翻目录找到页码再跳到那一页只读菜谱内容。Agent 处理 Skill 也是这个思路你在 Agent 环境里挂载了一堆 Skill 包Agent 接到用户问题时先读每个技能包的简短描述相当于菜谱目录它判断哪个技能包可能匹配当前任务再打开那个技能包的 SKILL.md看里面的具体步骤和示例只读取实际用到的细节其余内容继续留在磁盘上不占上下文。这套机制的直接收益有两个。第一知识可以复用了同一份技能包可以在无数个对话任务里反复挂载不需要每次手写一长串 Prompt第二上下文更省了模型只在需要时读取细节推理质量自然比满屏信息噪音高出不少。1.3 Skill 不是提示词模板也不是普通文档很多人把 Skill 看成复杂版的 Prompt 模板这个理解不准确。提示词模板是一次性粘贴给模型看的文本它没有入口描述和内部结构的概念而 Skill 是一个结构化的知识单元至少包含两层信息对外入口一段很短的描述告诉 Agent 我是什么、适合做什么Agent 据此决定是否唤起这个技能对内细节一份拆成若干小节的 SKILL.md按需读取。它就像是一个带目录和索引的小型技术文档而不是平铺直叙的一堆文本。另外普通文档是给人读的可以自由组织语言SKILL.md 是给模型读的它要让模型在低开销扫描和高精度执行之间找到平衡。写法和排版都有讲究这才是 Skill 设计真正有技术含量的地方。2. SKILL.md 到底长什么样文件结构解剖2.1 一个 Skill 包的标准目录Skill 的实现方式在不同框架里略有差异但核心构成基本一致。我以目前比较常见、社区认可度也比较高的 Claude Agent Skills 规范为例一个标准的 Skill 包通常长这样my-skill/ ├── SKILL.md # 技能描述文件Agent 主要读取这个 ├── scripts/ # 辅助脚本按需执行 │ └── format.py ├── templates/ # 模板文件生成内容时引用 │ └── report_template.md └── references/ # 深度参考文档只在特定场景读取 └── database_schema.mdSKILL.md是这个技能包的门面文件名固定、放在根目录下。Agent 框架通常会扫描技能包目录读取SKILL.md的头部信息作为技能索引。其余的scripts/、templates/、references/都是辅助资源Agent 只有在真正需要它们的时候才会去触碰。2.2 frontmatter 里的元信息为什么重要打开任意一份SKILL.md开头通常是一段 YAML 格式的 frontmatter--- name: sql-query-optimization description: 用于对慢查询进行性能分析和索引优化。当用户提供执行计划或怀疑 SQL 查询缓慢时使用。不要用于表结构设计。 ---name是技能的唯一标识通常用中划线连接的小写英文description是 Agent 判断什么时候该用这个技能的唯一依据。这段描述写得好不好直接决定整体效果。我总结出两个容易踩的坑描述太宽泛。比如用于 SQL 问题Agent 可能在写建表语句、生成 ORM 代码时也去激活这个技能导致答非所问。正例应该写明当用户提供执行计划或怀疑 SQL 查询缓慢时使用这种触发条件。描述没写边界。可以适当加一句不要用于表结构设计防止 Agent 在相关但不该用的场景下乱调用。给模型划清边界它反而会更听话。一段时间之后你会发现调模型很多时候不是在调模型本身而是在调这段 description 的措辞。它就像插件市场的简介文案直接影响能不能被用户在合适的时机搜到。2.3 body 内容怎么写才算合格frontmatter 后面的正文部分是模型真正执行时参考的手艺手册。正文写作有几个关键原则按场景分小节每个小节一个 H2 或 H3 标题。比如### 2.1 识别慢查询来源### 2.2 索引选择建议### 2.3 改写 SQL 示例。模型扫描时会先看标题再决定进哪个小节细读这正好契合渐进式披露的机制。步骤要具体给出输入 - 操作 - 输出链路。不要写对查询进行优化这种废话要写从 EXPLAIN ANALYZE 输出中识别 seq scan 操作若命中且表行数超过 100 万考虑添加覆盖索引。给示例而且给带输入输出的示例。模型对示例的模仿能力远强于对抽象规则的理解这一点和人类学习很相似。控制单文件体量。我建议一份 SKILL.md 控制在 200 行以内如果超过说明内容过载考虑拆成多个 Skill 或者把深层内容移到 references/ 目录。2.4 附带脚本、模板、参考文档的正确组织方式当技能包里的知识量比较大时不要硬往 SKILL.md 里塞代码表或完整模板利用辅助目录是更优做法scripts/放可执行的脚本比如数据处理脚本、文本格式化脚本。注意脚本尽量不要有交互式输入否则 Agent 调用时容易卡住把参数通过命令行传入更稳妥。templates/放输出模板比如周报模板、SQL 生成模板、代码提交说明模板。Agent 生成内容时会把模板读出来填充变量。references/放深度参考文档适用于大部分时候用不到但一用就要命的场景比如完整数据库 Schema、历史故障复盘。这类内容体积大、使用频率低放在子目录里让 Agent 按需读取能有效绕开上下文窗口的限制。我在实际项目中见过很多人把几千行的完整开源项目代码塞进 SKILL.md这基本是灾难。模型为了看其中一个小函数就不得不把上下文大部分空间让给无关代码。更好的做法是SKILL.md 里只写如何定位相关文件、如何修改具体代码用脚本去检索。3. 渐进式披露让 Agent 只看到该看到的东西3.1 渐进式披露的核心理念渐进式披露Progressive Disclosure是 Skill 设计中最核心、也最容易被忽略的部分。这个词最早来自 UX 设计领域意思是用户界面不应该一次性展示所有信息而是根据用户当前需要逐层暴露更多细节。放到 Agent Skill 的场景下它的含义是Agent 不应该一次性把技能包里的所有内容全部吞进去而是应该从简短摘要开始一层一层深入直到拿到解决当前问题所需的信息。这和人类上手新工具的逻辑一致——先看说明书目录再翻到对应章节只在必要时阅读故障排除部分。3.2 一次调用中的完整披露流程我试着模拟一下Agent 处理带 Skill 的任务时内部大致走了这么几步用户提问我这条 SQL 查了 3 秒怎么优化Agent 扫描已挂载技能包的 description 索引发现sql-query-optimization的描述命中查询缓慢关键词。Agent 打开这个技能包的 SKILL.md先读一遍所有 H2/H3 标题形成这个技能里有识别慢查询、索引选择、SQL 改写这几个部分的整体印象。Agent 判断当前任务是识别慢查询来源于是只精读### 2.1 识别慢查询来源小节拿到具体的 EXPLAIN 分析步骤。执行完第一步后如果需要改索引它再回头读### 2.2 索引选择建议小节。所有操作完成后SKILL.md 的其他小节内容可能从头到尾都没被读取也就没浪费任何上下文窗口。这个扫描 - 定位 - 精读的过程就是渐进式披露在运行时的真实流转。它能成立的前提是SKILL.md 本身必须结构清晰所有标题和信息点都能被快速扫描。3.3 一个档案袋式的例子文献检索 Skill为了把这个概念讲得更落体我举一个文献检索技能包的例子。假设我们有一个academic-paper-research的 Skill它的 SKILL.md 开头是--- name: academic-paper-research description: 用于中英文学术文献检索与综述整理。当用户需要查找论文、总结研究进展、梳理某个领域学术脉络时使用。不要用于写代码或日常信息查询。 --- # 学术论文检索与研究助手 ## 1. 检索策略设计 - 根据用户给定主题提取 3-5 组检索关键词 - 优先使用期刊数据库和预印本平台如 arXiv、CNKI、Web of Science - 按标题/摘要/全文三级匹配度筛选 ## 2. 文献筛选标准 - 优先近 3 年文献历史经典文献单独标注 - 按被引次数、发表期刊影响因子、作者团队相关性排序 ## 3. 综述写作框架 - 背景该领域为什么重要 - 进展近五年有哪些代表性工作 - 争议当前研究存在哪些分歧 - 展望下一步可能的方向当用户说帮我调研一下大语言模型推理加速的最近进展时Agent 第一轮会读到检索策略设计然后产出几组关键词并开始检索搜到的文献列表出来后它再回到 SKILL.md 读文献筛选标准小节对结果排序等到需要产出一份综述时它才去读综述写作框架。整个过程中这个 SKILL.md 文件始终只有几十行对 Agent 来说简直是轻量级负担。但如果你把检索策略、筛选标准、综述框架一次性堆进一个很长的 Prompt模型反而容易在执行到一半时把任务目标给忘了。3.4 披露粒度怎么把握实践下来我总结了几个关于披露粒度的经验SKILL.md 的总长控制在 60~200 行之间。太短则信息不够技能无法真正落地太长则模型扫描成本太高失去了渐进式披露的意义。用 H2/H3 标题把内容切成若干独立小节。每节只回答一个问题标题用动宾短语便于 Agent 快速定位。内容有依赖关系时明确写出来。比如在进入第 2 节之前必须先完成第 1 节的步骤避免 Agent 跳过必要前置步骤。不要把关键信息藏在很深的嵌套里。比如### 3.2.4 注意事项这种层级看起来有条理但对模型来说反而难以定位尽量控制在两层以内。4. Skill、Agent 与工具MCP的边界别再混为一谈了4.1 三者各干各的活现在社区里讨论 Agent 开发时经常把 Skill、Agent、工具MCP / Function Calling混在一起说很多新手被绕得晕头转向。我尽量用一句话划清边界Agent 是调度大脑负责理解用户目标、规划步骤、决定下一步调什么Skill 是知识和方法论告诉 Agent某类事情应该怎么做、有什么规范工具MCP/Function是执行手脚真正去做外部动作比如查数据库、发 HTTP 请求、操作文件。用餐厅类比Agent 是厨师长Skill 是菜谱和管理规范工具则是炉灶、锅铲和食材供应商。厨师长先看菜谱决定怎么炒再操起锅铲动手三者缺一不可。4.2 什么场景用 Skill什么场景必须上 MCP这两种机制经常会让开发者纠结。我的判断标准很简单如果任务主要是**按某种方法/流程产出内容**比如写周报、做代码审查、整理会议纪要、写论文综述那优先用Skill。它本质上是给模型提供怎么做的指导。如果任务是**访问外部系统、执行真实动作**比如查询 API 数据、写文件、调用命令行工具、发送邮件那必须用MCP 工具或 Function Call。模型需要真正执行一个动作并拿到结果不能只靠读文档就完成。大量复杂任务其实两者都需要。比如读取数据库中的慢查询日志然后根据优化规范输出调优建议——数据读取靠 MCP 工具优化规范和方法论靠 Skill。我把这两者的区别整理成一个表维度SkillMCP 工具Function Calling解决什么问题告诉模型怎么做替模型动手做载体SKILL.md 及附属资源可执行函数、API 接口输入输出方法指导、步骤、示例直接执行并返回结构化结果是否消耗上下文按需读取可控结果会进入上下文注意大小典型例子代码审查规范、写作框架、数据分析流程查询天气 API、读写数据库、执行 Shell4.3 实测项目里的组合玩法我自己维护了一个内部数据分析 Agent它同时挂载了 7 个 Skill 和 4 个 MCP 工具。用户输入分析本月订单数据并生成周报时实际执行链路是这样的Agent 读取技能索引激活>--- name: short-video-script description: 用于生成面向抖音、小红书、B 站的短视频脚本文案。当用户提供产品或主题并需要脚本创作时使用。不做视频拍摄建议和投放策略。 --- # 短视频脚本生成助手 ## 1. 素材整理 - 提取用户输入中的核心卖点归纳为 1-3 句话 - 标注目标平台与受众人群画像 ## 2. 脚本结构 - 黄金前 3 秒抛出反常识结论或痛点问题 - 痛点引入具体化目标用户正在经历的场景 - 解决方案给出 2-3 个可操作建议 - 案例故事讲一个具体的用户/使用场景故事 - 转化引导给出明确的下一步动作关注、评论、购买 ## 3. 平台差异 - 抖音节奏快、前 3 秒决定完播率 - 小红书重干货总结多使用清单体 - B 站互动性强适合做长铺垫和梗 ## 4. 编写禁忌 - 避免虚假夸大宣传 - 避免仅仅堆砌专业术语要翻译成用户语言 - 每个脚本必须给出一句可直接口播的结尾钩子把这份 SKILL.md 放进short-video-script/目录整个技能包就算成型了。第一次写不用追求完美关键是先让它能用再根据实际输出迭代。6.4 第四步用 agent 跑一轮真实任务来调参写完 SKILL.md 后直接拿真实任务测试。我的测试流程是输入一个简单需求帮我写一个家用咖啡机的短视频脚本目标是小红书用户观察模型的输出是否严格遵循了 SKILL.md 中的五段式结构对照 SKILL.md 检查是不是有哪个小节没被激活description 的触发词是否足够如果模型输出完全偏离优先检查description 是否写得足够精准其次检查正文指令是否过于模糊。这个迭代过程一般要跑 3~5 轮才能趋于稳定。我见过不少人写一次技能就希望它表现完美这不太现实技能的调试本质上和写代码类似需要基于反馈不断修正。7. 关于 Skill 生态与部署我的几点经验7.1 不同 Agent 框架对 Skill 的实现差异不同 Agent 框架对 Skill 的底层实现不尽相同。Claude 系的 Agent Skills 是相对标准化的 SKILL.md 规范社区贡献的技能包也多Codex 则有自己的一套 prompt 和 skills 机制更偏向在编码场景里按需注入OpenCode 也实现了类似的 skills 功能适合在本地终端环境里使用。还有一些新兴 Agent 框架会把 Skill 与 workflow、MCP 工具统一成一套调度体系。这里我不准备展开讲每个框架的具体配置方式因为更新迭代太快只看文档容易过时。核心经验是只要你理解了 SKILL.md 和渐进式披露的通用逻辑在不同框架间迁移的成本不会太高因为它们解决的本质问题是一致的。切换框架时优先看官方文档对 skill 目录规范和 description 字段的约束就可以快速上手。7.2 新手最容易踩的 3 个坑把这些年用 Skill 的经验浓缩一下新手最容易踩的坑主要集中在下面三个Description 写得像论文摘要。我见过有人花一整段话描述技能包的战略意义、项目背景结果 Agent 根本抓不住触发条件。description 应该像搜索关键词 触发条件而不是产品介绍。把所有知识塞进一个超大锦集 SKILL.md。有些朋友的技能包文件动辄几千行以为内容越全越好。实际上上下文窗口就那么大你塞得越满真正有用的那部分能被模型利用得越少。超过 300 行的技能包就应该拆。忽略版本与更新管理。技能包会随着团队规范调整而变化我在实战中吃过亏旧的代码审查规范文件一直挂在 Agent 上导致模型按过时标准检查代码。Skill 目录建议纳入版本管理和项目的其他文档一起维护。7.3 给想深入做 Agent 开发的人一个建议如果你正准备在项目里引入 Agent 开发我很建议从先把团队现有的文档、规范、经验拆成一组 Skill开始而不是一上来就追求复杂的 Agent 编排。把个人或团队的隐性经验结构化、挂载到 Agent 上这个动作本身就会带来立竿见影的效率提升。我自己在从零搭建 Agent 系统的时候最先做的永远是整理 Skill 清单后做 Agent 逻辑。因为技能包决定了一个 Agent会什么而 Agent 编排只决定怎么调度这些能力。先有足够多的靠谱技能再去编排整个系统才会稳。后续如果有机会我再把自己在 MCP 工具设计、Agent 编排层踩过的坑单独拎出来写一篇这次就先聊到这里。