1. 先搞清楚Skills到底是什么不是什么大概从2025年年初开始Skills这个词在AI开发圈里的出现频率突然高了起来一开始它还只是某个Agent框架文档里的一个小章节到后面几乎成了各家用模型和开发工具默认支持的标配能力。朋友圈里讨论的不再是你怎么调Prompt而是你给它配了哪些Skills。我第一次意识到Skills这东西值得当个正经事来研究是在一次调优Agent任务的场景里。当时我在用某个Agent跑一个批量文档解析的流程模型能力已经足够强了但每次处理同一类任务它的表现都忽高忽低——有时候自己会引出不存在的字段有时候格式说变就变。反复调了几轮Prompt都没有根治后来有人提醒我为什么不试试把经验写成Skills喂进去那一次尝试改变了我对AI开发方式的理解。先说结论Skills的本质是把某一类任务的做事方法打包成一个可复用的指令包让Agent在需要时主动调用它。它不像传统软件里的插件那样是一段段硬编码的函数逻辑而是「结构化的提示词参考素材可选的脚本工具」的组合体核心作用不是给Agent增加新功能而是教会它遇到这类事应该怎么想的、怎么做的。拿我们人类的工作方式来类比会更好理解。一个刚入职的初级工程师和一个干了十年的老工程师之间差的往往不是知识量而是面对同样问题时脑子里那套处理流程。老工程师拿到一个Bug不会直接上手改而是会先看日志、再复现、再定位根因、再写修复、再做回归这套思考习惯其实就是一种技能。常规文档里写的是系统架构是什么Skills里写的是遇到问题应该怎么处理。那它跟其他几个概念的区别在哪儿这是最容易让人糊涂的地方。我把它们分开来说。Plugin插件是一段真实的代码逻辑通常由Agent在特定场景下执行某个函数或调用某个接口。MCP Tool相当于把外部工具能力标准化成Agent能调用的一组服务本质上还是在执行动作。而Skills更偏向方法论层它描述的不是你能做什么而是你该怎么做这件事才算做好。有些Skills也会内嵌脚本但那通常是为了辅助处理格式转换、数据抓取这类机械化步骤。判断一个东西是不是Skills看它最重要的组成成分就行SKILL.md 描述文件是灵魂脚本和参考文档都是配菜。Harness就更不在一个层级上了它是整个Agent运行的基本框架负责编排模型调用、工具路由、上下文管理这些底层机制。可以说Skills是Agent跑在Harness之上时借助的知识和技能组件一个是容器一个是容器里装的弹药。有很多刚接触Agent开发的读者会把这三者混在一起实际架构里它们的层次差得很远。所以现在再回头看Agent开发必学的Skills这类话题你会发现它真正说的不是怎么给Agent装技能而是怎么把领域经验总结成一套Agent能理解的做事规范。这种开发方式和传统编程有一个本质差别传统编程是你在告诉计算机每一步做什么Skills开发其实是在整理一套专业判断逻辑让模型在执行任务时按照这套逻辑来思考。这才是整个Agent Skills话题最核心的认知起点。理解了这一点后面的一切操作——安装、设计、评测、迭代都是在围绕把做事方法论结构化这件事在不断打磨。2. 装一个现成Skills工具链的分化与安装实路概念清楚之后最直接的上手方式肯定是先找个现成的Skills用起来。目前主流Agent开发工具对Skills的支持已经相当成熟我实测下来主流选择集中在Claude Code、Codex、OpenCode这几个有代表性的工具上。每个工具对Skills的管理都有自己的一套约定但总体思路趋同。2.1 Claude Code的Skills目录约定Claude Code在比较早的版本里就加入了Skills支持它的目录约定非常简单把Skills放在~/.claude/skills/下面每个技能一个子目录目录下放一个SKILL.md文件和若干辅助资源。实际安装的时候手动复制是最直白的做法。从社区里下载一个Skills仓库比如跑git clone把仓库拉到本地然后把里面的某个技能目录直接放进去重开一下终端让它重新加载配置就能生效。我自己用下来更推荐用类似smithery或者一些社区整理好的Cli工具来做命令行安装这些工具会自动帮你做目录落位和版本检测省去手动复制的麻烦。不过要注意自动安装工具的更新速度不一定跟得上Agent版本节奏偶尔会出现兼容性问题手动复制反而更稳妥。2.2 Codex和OpenCode的差异点Codex在Skills的目录约定上跟Claude Code类似同样是把技能丢进~/.codex/skills/这样的目录结构。OpenCode也是差不多的思路。这类工具的Skills格式基本都是顺着Claude那套规范走的SKILL.md在前辅助文件在后所以其实社区里已经形成了一种事实标准。装好之后验证是否生效最粗暴也是最有效的方法开一个会话给Agent一个跟这个Skills强相关的小任务然后观察它的表现。一个有效的Skills会被Agent在思考过程中主动引用这一点从输出里能看到痕迹——比如它会按照SKILL.md里定义的步骤来拆分任务而不是走自己默认的反应模式。我在第一次尝试装了一个代码审查类的Skills之后明显感觉到Agent在分析代码时输出的结构从随意叙事变成了多阶段审查框架这算是Skills生效最直观的信号。2.3 常用Skills源社区里现在有不少整理好的Skills仓库GitHub上的awesome系列仓库比如awesome-claude-skills汇总了社区里比较活跃的Skills项目一些个人开发者维护的Skills市场类站点通常带在线浏览和说明文档各种技术社区里定期有人分享自己打磨过的技能包。这些源的质量参差不齐实际用的时候有几个坑要提醒第一看README不如看SKILL.md。仓库首页写得再漂亮都有可能过期SKILL.md里的内容才是实际喂给模型的东西。第二留意许可证和依赖。有些Skills写死了某个特定模型的行为习惯换到别的模型上效果会打折扣。第三不要装太多。这里说的不是存储空间而是上下文和记忆的负担——后面会详细展开讲这个坑。3. 现成Skills的局限性为什么我决定自己动手写社区里好用的Skills确实不少但随着我跑的项目越来越具体现成技能开始暴露出三个明显的短板。第一个短板是通用技能和真实业务场景之间的张力。社区里比较火的Skills往往是为了解决大众化问题的——代码审查、文档生成、Prompt优化这类通用主题。但实际工作中我的需求经常是针对某个内部项目的特定规范做检查或者按照某个固定的数据格式生成报告。这些通用技能拿来做一概而论的建议还行要它按照我的业务上下文来工作就完全不够用了。第二个短板是质量参差不齐且缺乏维护。很多Skill仓库是开发者一时兴起做出来的之后就不再更新。Agent框架在快速迭代Skills的写法约定也在变老旧的技能轻则效果不佳重则直接报错。第三个短板其实是核心痛点写Skills这个动作本身就是梳理业务知识的过程。一个真正贴合场景的Skills需要把你脑子里的隐性经验变成显性的步骤、规范和参考案例。现成的Skills再强也无法替代这个过程。所以我下定决心要自己写一个真正能用于实际工作的Skills。当时我选择了一个相对切身的场景Python项目的代码审查。找这个场景有两个原因一是代码审查本身有清晰的流程——初始化检查、依赖分析、代码结构审查、安全审查、测试覆盖检查、出具报告适合用Skills来承载二是在我自己日常的工作流里代码审查是一个高频动作把这个做好能立竿见影地提效。这个决定后来让我踩了不少坑但也真正把Skills开发的很多东西打通了。3.1 不写SKILL.md就动手先拆解你的任务开始动手之前我先做了一件事认真梳理一个资深工程师做Python代码审查的时候脑子里到底在想什么。这个动作极其重要。市面上大多数质量差的Skills问题就出在作者跳过了这一步直接把帮我审查代码这种笼统的指令写成SKILL.md然后发现模型输出的内容跟随便写一个Prompt出来的没啥区别。我把代码审查任务拆成了六个阶段建立上下文先了解项目类型、依赖关系、目标Python版本而不是上来就盯着某一行代码指手画脚结构审查看模块划分是否合理、循环依赖是否存在、目录结构是否符合项目定位代码质量审查检查函数复杂度、命名规范、重复代码、类型标注安全审查检查是否存在注入风险、不安全的反序列化、硬编码密钥测试评估看测试覆盖情况、测试质量、边界条件是否覆盖输出标准化报告按固定格式输出包含风险等级、问题清单、修改建议的审查结论。这一步的本质是让你从一个会写代码的人切换到能定义代码审查方法论的人。你定义得越细后面的SKILL.md就越有血有肉。3.2 用重新审视流程的方法拆解并定义技能边界拆完流程之后还要做一步很多教程不会提的事情定义技能边界。也就是明确这个Skills不做什么。比如我的Python代码审查Skills它只做纯静态审查不执行代码它关注代码质量和安全性不深入做性能压测它适合中小型项目不会假装能处理极其复杂的微服务架构。这些边界写上SKILL.md里看起来好像多此一举实际非常有用——它防止模型在你没让它做的时候自己发挥去执行代码或者输出一些你根本不需要的深度建议。做完这些准备才轮到真正动手写文件建目录结构、写SKILL.md主题和部分描述。这套先梳理方法论再编码实现的路径我个人强烈建议任何想自己写Skills的人都走一遍。4. 手把手写一个可用的Skills完整实操拆解4.1 目录结构一个最简但完整的Skills目录结构长这样python-code-review/ ├── SKILL.md ├── references/ │ ├── secure-coding-checklist.md │ └── severity-rules.md └── scripts/ ├── extract_dependencies.py └── detect_secrets.pySKILL.md核心描述文件模型主要靠它来理解这个技能是干嘛的references/存放一些参考文档模型需要时会读取有上下文需要再读不会白白占tokenscripts/放一些辅助执行的Python脚本比如提取依赖、扫描密钥这些机械工作。4.2 SKILL.md关键组成结构SKILL.md是Skills的简历写得好不好直接决定模型会不会用、用得对不对。我踩了几轮坑之后总结出一份相对好用的结构模板--- name: python-code-review description: 针对Python项目执行结构化代码审查输出标准化审计报告。适用于评估代码质量、发现安全风险和优化改进方向的场景。 --- # Python 代码审查技能 ## 适用场景 - 在收到一个Python项目/模块时进行系统性审查 ## 执行步骤 1. **了解上下文** - 确认项目类型Web应用/CLI工具/数据处理库等 - 读取依赖文件记录关键依赖版本 2. **结构审查** - 检查目录结构是否清晰 - 标记循环依赖和无用抽象 - ... 3. **质量审查** - 针对每个模块运行复杂度评估 - 检查是否符合PEP8标注存在问题的行号 - ... 4. **安全审查** - 调references/secure-coding-checklist.md逐项检查 - 使用scripts/detect_secrets.py扫描硬编码密钥 5. **测试评估** - 检查测试目录覆盖的关键模块 - 对比测试代码和被测试代码的复杂度标记测试薄弱区 6. **报告输出** - 按模板输出Markdown报告包含风险等级定义、发现的问题清单、每个问题的严重级别和修复建议 ## 关键注意事项 - 本技能只做静态审查不执行项目代码 - 对不确定的信息明确标注需人工确认而非臆断 - 输出报告使用中文这个structured最大的优点是可验证模型的每一步输出你都能对着SKILL.md去检查它有没有照做。很多网上流传的SKILL.md写得像销售文案——你会成为资深代码审查专家、以极高标准分析代码——这种话模型看过跟没看一样它们没有可执行的操作指令。4.3 scripts目录和references目录的用法写辅助脚本要守住一个原则只做机器擅长的事把判断留给模型。比如detect_secrets.py这个脚本它可以很高效地扫出代码里可能存在的密钥字符串但它判断不了这个密钥是不是真的敏感。所以脚本的输出应该是一份候选清单模型拿着这个清单结合上下文去做最终判断——这比全自动扫描准确得多也比让模型肉眼扫几千行代码高效得多。references/里的文档则是给模型按需查阅的。像secure-coding-checklist.md这种内容如果全部塞进SKILL.md会让每个任务都白白消耗好几千token放到references里之后模型只有在进入安全审查阶段才去读平时根本不占上下文。这个设计是Skills在工程效率和执行质量之间做的关键平衡。我用这个结构写过不止一个Skills也帮朋友定制过几个。从我实测的数据来看结构化的SKILL.md比自然语言堆砌的SKILL.md在同样模型上跑同样的任务输出稳定性和任务完成度至少高出两三成。这背后其实很好理解你把任务的思考过程和输出规范定义得越清楚模型扮演一个更确定性的执行器的能力就越强。5. Skills依赖与调试实测避坑记录写Skills这件事真正让人崩溃的往往不是写内容而是调试。我在这条路上踩过的坑不算少挑几个最有代表性的记录一下。5.1 SKILL.md里的工程禁忌禁忌一堆废话式指导。你应该表现得像一个专业的代码审查专家、请严格遵守高质量标准——这些东西写100句都不如一条具体的操作指令来得有用。模型不吃这一套它的推理过程需要可执行的步骤和明确的判断标准。禁忌二上下文贪婪。我一开始给Skills写了很长的定义文件把所有能想到的细节全塞进去结果模型每处理一个任务都要消耗巨量token去理解这些定义真正用来分析代码的空间反而被挤压了。后来我把一半以上的内容挪到references/里按需加载Token消耗直接降了一半任务完成质量反而提升了。禁忌三过度约束导致僵化。有些Skills写着写着会变成给模型下的军令状——必须用绝对固定的模板、绝对不能有输出之外的任何解释。这种过度约束会让模型失去柔性应变的能力遇到SKILL.md里没定义的情况就懵了。一个好的Skills应该像一套打法而不是一条铁轨。5.2 一套有效的调试方法通过小样本快速迭代调试Skills最有效的方法是用小样本场景测试法。我个人的操作流程是这样的准备3到5个有代表性的测试任务覆盖技能的典型场景和一些边界场景在同一个模型上分别测试没有Skills和挂了Skills两种情况对比输出差异记录每次输出的质量、token消耗、耗时针对不合格的输出去修改SKILL.md里对应的指令而不是全局重写重新跑同一组测试直到输出稳定。这基本就是一套AI时代的开发测试循环。我做一个中等复杂度的Skills通常要迭代四到五轮才能让输出质量稳定下来。5.3 版本管理意识很多Skills开发者完全没有版本管理意识改了一版之后忘记了之前的效果。我在实际工作中吃过大亏有一次我调整了一个Skills的某个步骤描述觉得自己改得更好了结果线上任务跑完出来一堆格式错误。回滚的时候因为没有备份只能靠重新思考补回来。后来我做的每个Skills都放在Git仓库里管每次修改前先commit并且记录修改动机和实测效果。为了方便我还在SKILL.md顶部加了一段变更记录。这个习惯在技能长期维护中特别重要尤其是当你的Skills开始被团队其他人使用的时候。6. 进阶评测、坑位与未来方向Skills的开发和调优走到一定程度你会发现最核心的瓶颈已经不再是怎么写SKILL.md而是怎么科学地知道这个技能到底好不好用。这里必须说当前社区对Skills评测这件事的意识普遍很弱大量Skills停留在作者觉得好用的阶段。6.1 评测Skills的核心维度我在自己的实践中把Skills的评测拆成四个可量化的维度评测维度说明我的评测方法任务成功率Agent挂了Skills后任务完成度是否提升同一组任务对比有无Skills的输出质量输出稳定性同样的任务跑多次结果是否一致同任务跑5次统计结果偏差度Token消耗Skills带来的token成本是否可接受统计每次任务的总Token消耗泛化能力换一个相似场景Skills是否依然有效用没训练过的相似任务做测试6.2 一个典型的评测案例我拿Python代码审查Skills做过一次正式的评测准备了一组6个任务其中包括一个规范的中型Flask项目、一个结构混乱的脚本库、一个包含硬编码密钥的Django项目、一个测试覆盖严重不足的数据处理模块。结果很有意思没有Skills的时候模型对前两个任务的输出还算勉强可用到第三个开始就乱了一部分安全问题漏掉不说输出格式每次都变。挂了Skills之后不仅6个任务的输出结构完全统一安全审查阶段还会主动去读references里的安全清单且每次都能发现至少两到三个我在准备测试时故意埋的坑。这个评测结果说明Skills真正强化的不是模型的智力而是模型做事的一致性。而对工程类任务来说一致性往往比偶尔的高光表现重要得多。6.3 常见坑位复盘除了前面提到的目录和结构坑之外还有几个容易踩的Skills冲突。如果你的Agent同时挂着好几个Skills这些技能之间可能会抢任务。我遇到过代码审查和代码优化两个技能同时对同一段代码输出建议的情况结果很分裂。解决办法是在SKILL.md里写清楚各自的适用边界。参考文件过于庞大。references目录里的文档也会累计占用上下文如果技能写得太贪婪Agent可能为了一个简单问题被迫读完整本手册。好的做法是把参考资料按主题拆细让模型只读它需要的部分。技能描述与实际能力不匹配。这是社区里最普遍的问题。Description里吹得天花乱坠实际执行却完全没到那个水平。这种不匹配对Agent的调用逻辑是致命的——模型本来是根据描述来判断是否调用某个技能的描述和实际能力脱节会导致它乱调或者不调。6.4 Skills的未来方向从技能到能力生态从更长的周期来看Skills的发展态势已经很明显了——它会从一个开发工具里的功能特性演变成一个完整的内容生态。有几个趋势值得关注第一是跨工具兼容会变得更重要。现在Claude Code、Codex、OpenCode各有自己的目录约定虽然SKILL.md的事实标准已经在形成但离真正的零成本迁移还有距离。谁能先把这一步跑顺谁就有机会成为这一层协议的主导者。第二是评测体系会逐渐成型。随着Skills数量爆炸市场会倒逼出一套能被大家认可的评测标准和排行榜体系。到时候下载量好评这种粗暴指标会被更精细的能力图谱取代。第三是语义理解和多模态技能。未来的Skills可能不只是文字指令还会包含更丰富的示例输入输出对甚至带一些多模态参考素材。模型在接任务时看到的不仅是该怎么做还有做成什么样算好。说到底Skills正在改变的不只是我们开发Agent的方式更是我们整理和传递经验的方式。以前一件复杂工作的经验封装在老师傅的脑子里现在可以把它模块化、版本化、可复用化。虽然这个生态还处在很早期的阶段各种规范和工具都在野蛮生长但方向已经很确定了把专业能力变成可以安装、管理、升级的模块这条路一旦走通Agent不再只是有一个聪明的脑袋而是脑袋里装着无数个领域专家总结出的技能。最后从我个人的体会来说这一套东西最有价值的不是某项具体技术而是它逼着你去把自己会做的事情重新拆解、重新表达。每一次写Skills的过程中你对自己到底是怎么做这件事的都会有一个更深的理解。仅凭这一点就值回票价了。
