我最初看到“skills”这个词以为就是个普通的能力清单或者招聘要求。直到有朋友拿它在 AI Agent 的场景里问我我才意识到在2025年的大模型工程语境下这个词已经被赋予了一套非常具体的工程含义Agent Skills即智能体技能。它不是提示词模板的简单变体也不完全是 MCP 那样的外部工具协议而是介于两者之间、专门用来给模型“喂经验”的一套标准化封装。这篇文章我就想结合自己的实操经验把 skills 这个概念的来龙去脉、设计思路、落地方法和踩过的坑完整梳理一遍。如果你正在做 Agent 应用纠结于该用 MCP 还是该用 skills或者写了十几个提示词但模型表现依旧不稳定这篇文章应该能给你一个相对清晰的切入点。1. Skills 到底是什么先给这个概念框个边界1.1 一句话定位给模型插上可调用的经验模块Agent Skills 最核心的定位是把“某个领域怎么做才专业”这件事固化成模型可以随时读取的本地知识包。想象一下你雇佣了一个聪明但经验不足的新员工你不可能每次任务都从头讲一遍流程更合理的做法是给他一份《岗位操作手册》和对应的工具告诉他“碰到这类任务先看手册、再调用对应脚本”。Skills 就是这份手册和工具的组合。从实现上看一个 skill 通常由三部分组成一个SKILL.md文件描述技能是什么、什么时候用、怎么用、一些辅助脚本或模板真正干活的代码或参考文件以及一个清晰的调用约定。与 MCP 这种“外部服务对接协议”不同skills 不是让模型去调用远程 API而是把知识、范例、脚本直接放进模型可访问的本地目录里模型根据任务内容自主判断是否加载。这套设计有一个很实际的价值降低模型做事的门槛。比如你想让模型写一份符合企业规范的发布公告与其在每次对话里堆砌大量规则不如把公告模板、禁用语列表、审批流程说明打包成一个release-notes技能。模型识别到相关需求时会自动读取这些材料生成的内容质量和一致性都会有明显提升。1.2 Skills 与 MCP 的边界别再混为一谈我经常被问到“skills 是不是就是轻量级 MCP”还真不是。两者解决的是不同层面的问题放在一起对比会更容易理解对比维度Agent SkillsMCPModel Context Protocol核心定位静态知识 本地脚本的封装动态数据 外部工具的标准协议运行方式模型按需读取文件无需常驻服务需要客户端、服务端建立会话通信依赖要求零外部依赖目录即安装依赖服务地址、鉴权、网络连通性适用场景文档生成、代码审查、专业咨询查数据库、操作第三方应用、实时查询维护成本改文件即可低成本服务端升级、接口变更需要谨慎管理实时性弱知识更新靠文件迭代强可对接最新数据用生活类比来说skills 更像是“技能书”角色读过之后就知道该怎么做事MCP 则是“工具箱接口”是角色伸手去拿工具、操作外部设备的那条通道。一个 Agent 完全可以同时具备两者用 skills 沉淀领域经验和专业判断力用 MCP 获取实时数据并执行落地动作。1.3 Skills 适合用在哪场景判断的实用标准不是所有需求都适合做成 skills。我自己在项目中摸索出一个简易判断标准如果一个任务的核心价值在于“按特定的专业方式完成任务”比如按规范写代码、按格式出报告、按流程做排查那它适合 skills如果任务的核心价值在于“拿到最新、最准确的外部信息”比如查库存、看订单状态、读天气那它更适合 MCP。举几个实际场景。代码仓库里面预置了编码规范希望模型在写代码时自动遵守缩进、命名、注释规则这适合做成code-styleskill。产品团队希望模型每次生成需求文档时都带上用户故事、验收标准和优先级定义这适合做成prd-writerskill。反过来如果你希望模型能在对话中查一下某个客户的订单记录那就需要对接真实的业务系统这时候应该走 MCP 而不是 skills。从这个角度看skills 更像是一条“经验固化”通道它让模型的输出天花板不再是训练数据的上限而是团队最佳实践的上限。这个定位是 MCP 替代不了的。2. Skills 的设计思路与工程化拆解2.1 技能目录的标准结构小即是美既然决定用 skills下一步就是决定怎么组织文件。当前主流做法是在项目中建立一个skills/目录每个子目录代表一个技能。一个设计良好的技能目录结构通常是这样skills/ └── code-review/ ├── SKILL.md ├── review_checklist.md ├── rules/ │ ├── concurrency.md │ └── error-handling.md └── scripts/ └── detect_todo.py这个结构的设计意图很关键SKILL.md是技能入口模型先读它理解“这个技能是干嘛的、在什么时候用、主流程是什么”。其他文件按角色拆成“知识参考”和“可执行脚本”两类。知识参考文件提供判断依据和标准脚本负责机械性检查。这种拆分我有两个体会第一它天然控制了加载成本。模型不需要把整个目录全读一遍它先读入口文件再根据实际需要决定是否深入。第二它让维护变得简单。团队成员想更新某个规范时只需要修改对应的 markdown 文件不需要动主流程。一个常见的反面案例是把所有内容堆到一个几十 KB 的SKILL.md里。结果模型每次处理任务都被大量无关描述占据上下文响应速度变慢关键内容反而容易被稀释。我个人的实践标准是入口文件控制在 50 行以内其他内容全部拆到子文件。如果入口文件需要超过 50 行才能讲清楚说明你对这个技能的边界定义还不够清晰。2.2 SKILL.md 的编排方法先让模型看懂“要不要用我”SKILL.md是整套技能体系里最重要的文件它的编排质量直接决定技能是否会被正确触发。我的建议是在一个固定段落里依次回答四个问题这个技能解决什么问题什么情况下必须使用什么情况下明确不要用使用步骤是什么。拿一个实际的技能入口文件来说# Code Review 代码审查技能 ## 技能定位 对代码变更进行系统性审查识别逻辑错误、安全隐患、性能问题与规范偏离。 ## 适用场景 - 用户要求审查代码、看看有没有问题、跑一下 review - 合并请求Merge Request提交前检查 - 排查线上问题需要回顾代码逻辑 ## 不适用场景 - 编写新功能代码而非审查既有代码 - 只做简单格式化不涉及逻辑判断 ## 使用步骤 1. 阅读变更文件清单 2. 按 review_checklist.md 中的顺序逐项检查 3. 输出问题列表按严重程度分类 4. 给出修复建议这个结构有几个值得注意的地方。“适用场景”写得越具体模型越容易做对触发决策反之只写“用于代码审查”模型会在很多无关场景下误用。另外“不适用场景”不是可有可无的内容它负责划清边界避免模型滥用技能。写入口文件时还有一个容易被忽视的点描述行为而不是描述意图。与其写“提升代码质量”这种主观目标不如写“检查是否有 TODO 遗留、是否有未处理的错误分支、是否有竞态条件”。行为描述是模型可直接执行的指令意图描述则需要模型二次推断推断一旦出错执行就会漂移。2.3 渐进式披露把黄金信息放在加载链最前端“渐进式披露”是 Skills 设计的一个核心理念英文叫 progressive disclosure。这个理念的基础认知是大模型的上下文窗口永远都嫌小一次性灌入所有信息不仅费 token还会造成注意力稀释。正确的做法是分层披露入口文件只展示概览和关键决策点深水区的知识放在子文档里用明确的索引关系建立检索路径。我经常这样类比这就像做技术文档你不可能在 README 里写完所有 API 说明正确的做法是 README 告诉你“有哪些模块、各自是干嘛的、什么时候看哪个文档”让读者按需深入。SKILL.md 与附属文档的关系本质上就是 README 与详细文档的关系。渐进式披露反过来也要求技能作者具备“信息分级”思维。每次往技能里加内容时先问一句这条信息属于“触发判断”层级还是“执行过程”层级还是“参考查证”层级只把第一层级的内容放在入口文件第二、第三层级放到子文档。用这种思维维护技能时间长了你会明显感受到模型响应质量的稳定。3. 从零实现一个 Skill完整实操全过程3.1 准备基础环境与目录骨架理论讲再多不如直接上手做一个。这里我以“Python 单元测试技能”为例完整演示一个技能从零到一的过程。这个技能的目标很纯粹让模型在收到“写测试”“补单测”“完善测试覆盖”类需求时能够按团队标准自动生成符合规范的测试代码。第一步建立目录骨架mkdir -p skills/py-test/ cd skills/py-test/ touch SKILL.md touch test_template.py touch guidelines.md touch examples.md这四个文件各司其职SKILL.md是入口和触发判断test_template.py是测试代码模板guidelines.md是团队测试规范examples.md是参考示例。在开始编写任何内容之前我会强制自己先想清楚技能边界这个技能到底覆盖哪些能力答案在我这里是有限的四个能力——生成测试用例、组织测试类结构、mock 外部依赖、断言结果验证。超出这四个能力的都不往这个技能里塞。3.2 定义触发条件与焦点领域接着编写SKILL.md的触发判断部分。这部分相当于技能的“门卫”做得好不好会直接决定模型在正确的场景下会不会想到用它。我在实际项目中反复打磨后总结出一套可复用的触发条件写法# Python 单元测试技能 ## 焦点领域 pytest 风格的单元测试编写覆盖以下场景 - 为新函数或新类编写第一版单元测试 - 为既有函数补充缺失的异常分支测试 - 使用 mock 隔离外部依赖数据库、网络请求、文件系统 ## 目标框架 pytest unittest.mock ## 明确不做的事 - 不生成集成测试、端到端测试 - 不处理性能测试脚本 - 不负责 CI 流水线配置这个“明确不做的事”列表在初始版本里往往会被忽略但它其实是防止模型越界的关键。我在一个生产项目里曾经遇到过模型把集成测试也写进单测技能的场景导致维护混乱从此以后每个新建技能我都会认真写“不做的事”。3.3 编写核心知识文件与模板完成触发判断后进入核心内容编写阶段。首先是guidelines.md它承载这个技能的专业深度。我把自己在真实项目中积累的测试规范沉淀成文件# Python 单元测试规范 ## 测试命名 - 测试文件以 test_ 前缀命名与被测模块对应 - 测试函数以 test_ 开头名称应描述行为而非实现 - 测试类使用 CamelCase加 Test 后缀 ## 结构规范 - 每个测试类固定包含 setup_method 进行初始化 - 测试方法必须覆盖正常路径、边界路径、异常路径 - 断言信息必须包含失败原因说明 ## Mock 规范 - mock 只用于外部边界不 mock 被测对象自身的方法 - 使用 autospec 确保 mock 的接口签名与被替身一致 - mock 的恢复必须在 teardown 中完成然后写test_template.py这个文件的意义在于让模型直接套用可编译、可运行的模板而不是凭空生成格式各异的代码import pytest from unittest.mock import Mock, patch class TestExampleClass: 模板测试类使用时替换为实际被测类名 def setup_method(self): self.instance ExampleClass() def test_normal_path(self): 正常路径输入合法参数返回预期结果 result self.instance.method() assert result is not None, 预期返回非空结果 def test_boundary_path(self): 边界路径空值、最大值、空列表等场景 with pytest.raises(ValueError): self.instance.method() def test_exception_path(self): 异常路径非法输入触发预期异常 with pytest.raises(KeyError): self.instance.method(missing_keyTrue) def test_external_dependency_mocked(self): 外部依赖注入mock 掉网络请求只验证自身逻辑 with patch(module.path.api_call) as mock_api: mock_api.return_value {ok: True} result self.instance.process() mock_api.assert_called_once() assert result[ok] is True这个模板本身不复杂但它的存在价值非常大。它相当于给了模型一个“标准答案样板”模型生成测试代码时会有更大概率遵循项目内已有的组织方式而不是每次都从零发挥。3.4 测试技能效果与迭代优化技能写完不是终点验证和迭代才是真正让技能变好用的环节。我的验证流程通常分三步第一步做“提示语测试”。直接给模型一堆不同类型的需求比如“给 utils.py 里的 parse_config 函数写测试”“帮我补一下 user_service 的分支覆盖”“写一个性能测试脚本”看它是否能在正确场景下触发py-test技能在不适用场景下拒绝触发。第二步做“结果抽查”。让模型基于项目里的真实代码生成测试用例随机抽取其中三个手写一遍对照检查是否覆盖了边界异常、mock 是否正确恢复、断言信息是否真的有诊断价值。容易出问题的地方是断言信息模型默认生成的断言往往只是assert result expected没有失败原因描述这在新手接手时体验很差。第三步做“回归迭代”。把发现的共性问题写成新条目追加到guidelines.md填充到示例文件的对应位置。例如经过一轮迭代后我发现在 mock 外部依赖时模型经常忽略autospec参数于是在规范里增加了强制要求——这一步虽然小但对测试稳定性提升非常明显。3.5 多技能并存时的命名与索引规范技能数量少时不需要考虑命名规划超过五个之后命名问题立刻浮出水面。我在一个内部平台里维护了十多个技能第一次遇到的问题是“相似技能混淆”。例如有一个技能叫code-review另一个叫security-review模型在处理安全代码审查时可能错误触发前者。后来我建立了一套命名约定领域-动作格式例如python-test、api-doc-generator、db-migration-check。同时在每个SKILL.md的适用场景里加了“相关技能”引用形成导航关系。这样模型即使误触发了某一个技能也会在入口文件里看到指向真正正确技能的路标纠错成本大大降低。4. Skills 进阶多技能编排、权限与团队维护4.1 技能粒度控制从单一职责到组合复用技能粒度怎么控制是我见过最多人纠结的问题。有人认为技能越细越精确于是把一个“写周报”技能拆成“整理本周完成事项”“梳理下周计划”“生成周报模板”三个技能也有人走相反路线把 Python 后端相关的所有能力塞进一个大而全的backend-engineer技能里。这两种方向我都在项目里遇到过坑。拆得过细模型很难判断该用哪个子技能合得过大上下文被无关信息占满核心技能反而被稀释。最终我采用的是“单一职责 可选组合”的粒度策略每个技能只负责一个完整的任务闭环但允许技能之间相互引用形成组合。举个例子我没有单独做一个“写测试”技能和“写文档”技能再融合成“完成开发任务”而是让python-test技能专注于测试本身让api-doc-generator专注于接口文档。模型在完成一个开发任务时可以先加载python-test生成测试再加载api-doc-generator生成文档两者通过主任务的上下文自然衔接而不是物理上合在一起。在实践里我给技能粒度设置了一个“判断问题”如果一个技能被加载后模型仍然需要大量额外指令才能完成目标那说明粒度太粗如果一个技能只负责“取个变量名”这种单一动作那说明粒度太细。能在一个技能内部完成“输入—处理—输出”的完整闭环就是比较合适的粒度。4.2 权限边界与资源消耗控制Skills 在执行过程中可能会触发脚本、读写文件、甚至调用本地服务。权限控制因此成为一个不能回避的话题。我的经验是除非必要技能内的可执行脚本应该只做纯计算和文本处理不做任何有副作用的系统调用。比如上面演示的test_template.py是一个纯文本模板它不会真的去执行测试。如果某个技能里确实需要运行命令比如环境检查类技能需要执行pip check我会额外加一层约束脚本只能接收明确传入的参数输出必须结构化不能交互式操作。这条约束在团队协作时特别重要否则一个技能被不同成员使用时行为可能千差万别。资源消耗主要关注两个指标token 消耗和模型注意力损耗。我踩过的坑是在技能里放了过多“为了完整性而存在”的参考文档。比如一个代码规范技能我把 Python 风格指南的全文放进去结果每次触发都消耗几千 token而模型真正需要关心的核心规则其实只有二十来条。后来我把全文替换成“重点规则清单 官方文档链接”问题立刻缓解。4.3 版本演进与团队协作让技能成为团队资产技能的维护与其说是技术问题不如说是工程管理问题。我推荐的模式是“一技能一分支评审后合并”。每个技能在独立分支上进行迭代修改完成后提交 diff由团队中实际使用该技能的同事评审。评审重点不是代码风格而是行为描述是否准确、边界声明是否完整、示例是否能覆盖真实业务场景。版本更新方面我习惯在SKILL.md的头部加一段last-updated字段和changelog列表。这个习惯让我能快速定位“为什么这周模型表现不如上周”之类的问题——很多时候就是因为某次更新改写了触发条件导致模型在错误的场景下做出了不同的行为判断。技能是团队经验的固化所以团队协作时还有一个要提前达成共识的点技能文件必须用纯文本格式保存禁止用 PDF 或 Word。因为纯文本才能被模型直接读取索引。谁在团队里上传了个 PDF 版的《安全评审规范》那这个技能基本就废了。5. 常见问题与排查技巧实录5.1 问题速查表我从实际操作中整理了四个高频问题按频率排序症状可能原因排查步骤解决方案技能完全不触发触发描述过于模糊模型无法建立匹配关系检查SKILL.md的适用场景是否用了具体行为描述补充更多关键词和行为示例必要时加入“不适用场景”反向约束触发过于频繁适用场景列表太宽泛边界描述缺失查看触发上下文确认模型在哪些场景误用了技能强化“明确不做的事”列表收紧焦点领域描述输出质量不稳定技能内容组织混乱关键规范被淹没检查核心规范文件是否过长、是否存在重复表述按渐进式披露原则重排文件将关键规范前置示例单独成文加载成本过高附加大文件过多知识密度不足统计每次触发消耗的 token 数定位大文件占比用“重点清单 链接”的形式替换全文引用5.2 实操中容易忽视的三个细节第一个细节SKILL.md和辅助文档之间的索引关系不够明确。模型读完入口文件后需要根据索引去查找详细内容。如果索引只有一句“详见相关文档”模型可能不会继续深入。正确的做法是给出带路径的明确指引例如“执行阶段请读取guidelines.md的 Mock 规范章节参考examples.md中的第 3 个示例”。路径越具体模型检索越可靠。第二个细节示例文件没有覆盖边界场景。我发现只提供正常路径的示例会导致模型生成的内容永远停留在“正常情况”遇到异常输入或边界条件时就频繁犯错。合理做法是每个技能至少配一个包含非正常输入的示例。比如py-test技能的examples.md里我会专门放一个“如果被测函数在异常时应抛出 ValueError”的测试示例这样模型才会把异常分支纳入生成范围。第三个细节技能修改后没有回归测试。很多团队改了技能就提交没有验证改动是否影响了原有任务的输出。我的做法是保留一组成熟的“金标测试用例”每次修改技能后跑一遍对比输出和改动前的差异。如果核心输出出现非预期漂移立刻回滚并分析原因。这个流程虽然简单但在长期维护中性价比极高。5.3 从坑里爬出来后的几点心得养了这么久的 skills心里最深的体会是它不是一个“配置一次就万事大吉”的东西而是一套需要持续运营的组织资产。模型的行为不可能一次调到位技能库也不可能一次设计完美。我在这篇文章里讲的每一步从触发判断到渐进式披露到回归验证本质上都在做同一件事——让技能的使用门槛尽可能低、行为确定性尽可能高、维护路径尽可能清晰。如果你现在正准备在项目里引入 skills我的建议是从一个小而真实的痛点开始。挑团队里每周都被频繁问到的那个问题做成第一个技能跑通后再横向扩展。不要一上来就追求大而全的技能矩阵那样只会把维护成本推到一个不可持续的水平。技能库本质上是为模型服务的知识服务系统它的价值不是数量多而是每一次加载都能清晰地帮模型做对一件事。