文章目录
-
- 前言
- [1 先搞懂：Skill到底是个啥](#1 先搞懂：Skill到底是个啥)
-
- [1.1 一个接地气的类比](#1.1 一个接地气的类比)
- [1.2 Agent能力的四层架构](#1.2 Agent能力的四层架构)
- [1.3 什么时候该沉淀一个Skill](#1.3 什么时候该沉淀一个Skill)
- [2 当前公开规范的核心结构](#2 当前公开规范的核心结构)
-
- [2.1 完整目录长啥样](#2.1 完整目录长啥样)
- [2.2 三层理解法](#2.2 三层理解法)
- [2.3 每个目录的设计职责](#2.3 每个目录的设计职责)
- [2.4 SKILL.md的两部分](#2.4 SKILL.md的两部分)
- [3 加载方式：渐进式披露](#3 加载方式：渐进式披露)
-
- [3.1 核心设计思想](#3.1 核心设计思想)
- [3.2 完整加载链路](#3.2 完整加载链路)
- [4 Skill一般放在哪](#4 Skill一般放在哪)
-
- [4.1 四种常见存放路径](#4.1 四种常见存放路径)
- [4.2 优先级规则](#4.2 优先级规则)
- [5 从零构建一个Skill的步骤](#5 从零构建一个Skill的步骤)
-
- [5.1 第一步：挑一个足够窄的任务](#5.1 第一步：挑一个足够窄的任务)
- [5.2 第二步：先写触发描述，再写正文](#5.2 第二步：先写触发描述，再写正文)
- [5.3 第三步：把流程写成可执行的步骤](#5.3 第三步：把流程写成可执行的步骤)
- [5.4 第四步：按需拆分资源](#5.4 第四步：按需拆分资源)
- [5.5 第五步：验证Skill，不是只验证文案](#5.5 第五步：验证Skill，不是只验证文案)
- [5.6 第六步：版本化和维护](#5.6 第六步：版本化和维护)
- [6 一个可直接复制的最小示例](#6 一个可直接复制的最小示例)
- [7 自研Agent怎么实现Skill支持](#7 自研Agent怎么实现Skill支持)
-
- [7.1 七个核心环节](#7.1 七个核心环节)
- [7.2 设计原则](#7.2 设计原则)
- [8 常见翻车现场和改进建议](#8 常见翻车现场和改进建议)
- [9 发布前检查清单](#9 发布前检查清单)
- [10 最后说两句](#10 最后说两句)
P.S. 无意间发现了一个巨牛的人工智能教程，非常通俗易懂，对AI感兴趣的朋友强烈推荐去看看， 传送门https://blog.csdn.net/H1727548
前言
做Agent开发的朋友，大概率都踩过同一个坑。
你辛辛苦苦写了一大段提示词，当时测着效果贼好，结果过两天再跑，输出直接歪到姥姥家。
合着大模型也是弹性工作制？状态好的时候堪比资深专家，状态差的时候像刚入职的实习生瞎蒙。
想要让Agent稳定干活，不是靠堆提示词长度，而是得靠标准化的能力模块------也就是今天聊的Agent Skills。
1 先搞懂：Skill到底是个啥
1.1 一个接地气的类比
很多人以为Skill是个新模型，或者是个新API。
真不是。它更像给Agent配的可装载工作手册。
什么时候该用这个能力，按什么步骤走，能调用啥工具，出问题怎么处理，最后怎么验收结果，全写在里面。
说白了就是把老员工的经验固化下来，换谁来干都按这个流程走，不至于发挥失常。
1.2 Agent能力的四层架构
想搞明白Skill的位置，咱可以把Agent能力拆成四层，跟开饭店一个道理。
第一层Tool：就是菜刀、炒锅、削皮刀。干单个具体动作，切菜就用菜刀，炒菜就用炒锅。
第二层MCP：就是燃气管道、生鲜供应链。用标准方式接外部资源，不用你自己挨个谈合作。
第三层Skill：就是后厨操作SOP。先切啥后炒啥，火候多大，放多少盐，出餐标准是什么，全给你定死。
第四层Plugin：就是整店加盟方案。好几个Skill加供应链加管理规范，一套完整能力直接打包给你。
划个重点：Skill是编排工具的，它本身不是工具。别搞混了。
1.3 什么时候该沉淀一个Skill
不是啥任务都值得做个Skill，搞多了反而累赘。
判断标准很简单：这类活会不会反复干，而且步骤、标准、边界比临时发挥重要。
比如代码审查、接口测试、会议纪要转任务，这种高频又有标准的，就适合做Skill。
当然也别盲目堆Skill。现在大模型越来越聪明，太繁琐的Skill反而会变成枷锁。
就像你给老厨师塞一本新手菜谱，人家不仅用不上，还嫌你碍事。
真正值得做的，是通用模型搞不定的垂类深度场景。
2 当前公开规范的核心结构
2.1 完整目录长啥样
Agent Skills有标准的目录结构，分必填项、可选项和工程附属文件。
核心必填的只有一个：SKILL.md，相当于整个Skill的主说明书。
然后有几个规范可选目录：scripts放可执行脚本，references放参考资料，assets放模板样例。
还有客户端扩展用的agents目录，做质量评测的evals目录，以及许可证之类的附属文件。
听起来文件夹多，其实各司其职，不乱。
2.2 三层理解法
这么多目录不用死记，按三层逻辑捋就清楚了。
第一层是核心规范：SKILL.md是必须的，scripts、references、assets是官方认可的可选目录。
第二层是客户端扩展：比如agents目录里的配置，是给技能列表和UI展示用的。
第三层是质量工程：比如evals目录，放评测用例，运行时根本不用加载。
2.3 每个目录的设计职责
每个目录干啥的，给你说透。
scripts：放确定性操作的脚本。比如数据提取、格式校验，这种机械重复的活，交给脚本比让大模型靠谱。
references：放长篇知识。比如技术规范、决策表、错误码，不用的时候不加载，省上下文。
assets：放静态资源。比如输出模板、样例数据，直接套用就行。
evals：放评测用例。用来测Skill好不好用，不是给Agent运行时读的。
提醒一句：别把密钥、隐私数据随便塞Skill包里，安全第一。
2.4 SKILL.md的两部分
SKILL.md是核心，分两部分：YAML头信息和Markdown正文。
头信息干啥用？让Agent扫一眼就知道这个Skill是干啥的，要不要激活。
里面必填的就俩：name和description。名字要规范，描述是判断激活的核心依据。
剩下的许可证、兼容性、自定义元数据、授权工具，都是可选的。
正文部分，就是详细的执行说明。不用写得像百科全书，把场景、步骤、分支、输出、异常说清楚就行。
记住：正文越啰嗦，关键信息越容易被淹没。长内容拆去references里。
3 加载方式：渐进式披露
3.1 核心设计思想
这个规范最聪明的设计，就是渐进式加载，说白了就是挤牙膏，用多少挤多少。
分三层加载。
第一层发现阶段：只加载名字和描述。就像刷短视频，先看封面标题，感兴趣再点进去。
第二层激活阶段：任务匹配上了，再加载完整的SKILL.md正文。
第三层执行阶段：具体步骤用到哪个文件，再去读哪个脚本、参考资料。
好处很明显：不浪费上下文。总不能一上来就把几百个Skill的内容全塞进去，大模型直接就被撑懵了。
3.2 完整加载链路
整个流程走下来是这样的。
用户发了任务，Agent先扫一遍所有Skill的名字和描述。
不匹配？那就按普通流程走。
匹配上了？再把完整的SKILL.md读进来，按流程走。
流程里需要用到脚本或者参考资料？再单独去读对应的文件。
最后调用工具执行，验证结果，输出交付。
说直白点，这就跟相亲一样。先看头像简介，合眼缘再聊聊天，真要谈婚论嫁了再深入了解家底。
哪有一上来就把户口本、工资单、体检报告全甩出来的，那不叫真诚，叫社交恐怖分子。
4 Skill一般放在哪
4.1 四种常见存放路径
规范没强制要求安装目录，但行业里有通用约定，一般用.agents/skills目录。
项目级：放在当前项目的.agents/skills里，只对这个项目生效。适合业务专属规则。
用户级：放在用户目录下，当前用户所有项目都能用。适合通用开发、写作流程。
客户端原生目录：各个Agent产品自己定义的目录，功能可能多，但跨端复用性差。
组织级/内置目录：企业部署的时候统一放，适合全公司通用的合规、标准流程。
4.2 优先级规则
要是同名Skill好几个地方都有，按什么来？
通用优先级：项目级 > 用户级 > 内置默认。
毕竟离项目越近，针对性越强。就像公司规定不如部门规定，部门规定不如项目组的具体要求。
提醒一句：项目级的Skill跟着代码仓库走，可能是别人写的，生产环境加载前最好做个信任校验。
别啥来路的Skill都直接跑，容易出安全事故。
5 从零构建一个Skill的步骤
5.1 第一步：挑一个足够窄的任务
很多人做Skill，一上来就想搞个大的，比如"帮我做全栈开发"。
听我一句劝，别搞这种大而空的。做出来也是啥都能干一点，啥都干不好。
正确的打开方式，是挑一个非常垂直、非常具体的场景。
比如"审查Go HTTP服务的变更""生成Java接口测试用例""把会议纪要转成可追踪任务"。
场景越窄，描述越清晰，Agent越容易精准触发，效果也就越稳定。
贪多嚼不烂，这话放哪儿都对。
5.2 第二步：先写触发描述，再写正文
别上来就哐哐写正文，先把description写明白。
就一句话回答两个问题：这个Skill能干啥？用户啥时候会用到它？
可以加一些同义表达和典型场景，但别把完整流程都塞进去。
毕竟description是敲门砖，用户扫一眼就知道该不该用。写太长了，谁有耐心看。
5.3 第三步：把流程写成可执行的步骤
正文的步骤，别写空话。
别写"认真检查，确保质量"，这种话跟老板说"好好干，将来亏待不了你"一样，听着正确，啥用没有。
要写就写具体的：先读变更范围，再跑指定测试；测试失败就输出错误并停止发布。
每一步都要有动作、有判断、有下一步。
尤其涉及到写文件、删数据、发消息、部署这种高风险操作，一定要写清楚预览、确认、回滚或者人工审批。
不然Agent手一抖给你删库了，哭都来不及。
5.4 第四步：按需拆分资源
别啥内容都往SKILL.md里塞，该拆分就拆分。
确定性强、重复用的程序，放scripts里。比如数据提取、格式检查、生成报告。
长篇的领域规范、API约定、错误码，放references里。正文用到的时候再引用。
模板、样例数据、配置骨架，放assets里。直接套用，省得每次重新写。
各司其职，才好维护。
5.5 第五步：验证Skill，不是只验证文案
写完不是就完事了，得测。
别光读一遍觉得写得挺好就上线了，那叫自欺欺人。
至少准备四组用例：正向能触发的，负向不该触发的，边界条件的，异常输入的。
测啥呢？测该激活的时候能不能激活，测会不会去读脚本和参考资料，测守不守输出格式，测出问题会不会停在安全边界。
基础格式可以用工具校验，质量层面一定要做对照测试，开Skill和不开Skill对比着看。
不然你怎么知道这Skill是加分了还是帮倒忙了。
5.6 第六步：版本化和维护
Skill不是一锤子买卖，写完就不管了。
放进Git里管理，每次改了啥、为啥改、影响啥，写清楚。
流程变了、工具接口变了、安全规则变了，对应的正文、脚本、测试用例都得同步更。
尤其是改description的时候，一定要做回归测试。这玩意直接影响触发召回，改歪了可能就再也唤不醒了。
6 一个可直接复制的最小示例
光说不练假把式，给你个最简单的例子，面向Go服务变更审查的，直接就能用。
目录结构很简单：一个SKILL.md，scripts里放覆盖率检查脚本，references里放编码规范和常见bug，assets里放审查模板。
SKILL.md头信息里写清名字、描述、协议、兼容性、版本。
正文就几块：适用场景、输入要求、工作流、异常处理、验证方式。
工作流一步步写死：先读diff，再跑go vet，查覆盖率，对照规范，输出报告。
异常情况怎么处理也写明白：go vet失败就停，覆盖率降太多就标人工审核。
麻雀虽小，五脏俱全。照着这个路子改，就能做自己的Skill。
7 自研Agent怎么实现Skill支持
7.1 七个核心环节
要是你自己在做Agent，想支持Skill，不用搞成复杂的插件系统。抓住七个环节就行。
第一发现：扫各个目录，找出带SKILL.md的文件夹。别啥目录都扫，.git、node_modules这种跳过。
第二解析：读YAML头信息，至少拿出名字、描述和文件路径。解析失败的就别放进目录里。
第三建目录：把名字、描述、路径给模型。就放精简信息，别一股脑全塞进去。
第四激活：让模型根据描述判断要不要用，匹配上了再读完整正文。也可以做个手动激活命令。
第五资源访问：正文里引用的相对路径，按Skill根目录解析。用到哪个读哪个，别全加载。
第六权限信任：项目级的Skill要做信任判断，脚本、写文件、高危命令要做权限控制。别光靠Skill里的配置当安全边界。
第七观测：把发现、激活、资源读取、执行失败这些都记下来。方便后面排查为啥某个Skill没触发，或者为啥出问题。
7.2 设计原则
做实现的时候记住一个原则：格式兼容和产品特性分开。
标准的目录、文件格式、加载逻辑，尽量跟通用规范对齐，这样Skill能跨端复用。
自己产品的特色功能，比如专属安装路径、命令、权限模型、钩子，自己加就行。
但别改核心格式，改完就不通用了，等于自己造了个封闭生态。
8 常见翻车现场和改进建议
说几个大家做Skill最容易踩的坑，看看你中了几个。
第一个坑：描述写太泛。比如"帮助开发"，那啥开发任务都能触发，结果就是天天误触发。解决办法就是加明确的对象、动作、场景，太泛就拆成多个Skill。
第二个坑：SKILL.md写太长。激活之后上下文全被占了，关键步骤反而被淹没。解决办法就是正文只留工作流，长规范扔references里。
第三个坑：全是原则没有动作。通篇"保证安全""确保质量"，没说具体怎么做。解决办法就是把要求改成具体的检查、命令、判断分支。
第四个坑：脚本不可复现。依赖一堆隐藏环境变量，换个机器就跑不起来。解决办法就是写清依赖，参数明确，加错误提示和样例测试。
第五个坑：把Skill当权限系统。觉得Skill里写了能执行命令，就不用安全校验了。别闹，安全控制必须在工具层做，Skill说了不算。
第六个坑：不做负向测试。只要带关键词就触发，风马牛不相及的任务也往里凑。解决办法就是加负向用例，测召回率和误触率。
9 发布前检查清单
最后发布之前，对着清单过一遍，省得上线出问题。
名字和目录一致，符合命名规范。
描述清晰，说清干啥的、啥时候用。
正文是可执行的步骤，不是空泛的原则。
长篇内容都拆分到references里了。
脚本有明确的输入输出和依赖说明。
至少两三个评测用例，有正向有负向。
高风险操作有预览、确认或者回滚机制。
没硬编码密钥和隐私数据。
基础格式校验通过。
做过开Skill和不开Skill的对比测试。
提交记录写清了变更原因和影响范围。
10 最后说两句
说白了，Agent Skills本质就是把隐性的经验变成显性的规则，再把显性的规则变成可执行的流程。
它没什么高深的技术，但需要你转个思路。
从写提示词，变成设计流程。
从一次性方案，变成可复用的模块。
从贪大求全，变成小而精准。
从全靠模型发挥，变成用流程保障结果。
把Skill当成一个可测试的流程产品来做，而不是一段随便写写的提示词。
这才是Agent从花架子Demo，变成真正能干活的生产工具的关键一步。
P.S. 无意间发现了一个巨牛的人工智能教程，非常通俗易懂，对AI感兴趣的朋友强烈推荐去看看，传送门https://blog.csdn.net/H1727548