1. 从skills这个热词说起它到底指什么最近一段时间不管是在技术社区还是各种开发者群组里skills这个词出现的频率高得离谱。很多人第一次看到skills这个词的时候第一反应是技能这个通用含义但在当下的技术语境里它已经变成了一个非常具体的概念——Agent Skills也就是给 AI 智能体AI Agent使用的可插拔能力模块。我最初接触这个概念的时候也走了不少弯路。当时看到别人说装个 skills 就能让 agent 自动干活我以为是某种插件市场点进去发现完全不是那么回事。后来花了两三天时间把官方文档、社区讨论、实际项目都翻了一遍才真正搞明白这套东西的设计逻辑。这篇文章就是把我这段时间的理解和实操经验完整地梳理出来不管你是刚听说这个词的新手还是已经用过几个 skills 但没搞懂底层原理的开发者应该都能从中找到有用的东西。先把最核心的问题说清楚Agent Skills 本质上是一组结构化的指令文件用来告诉 AI 智能体在特定场景下应该怎么做。它不是一个软件包不是一个 API也不是一个需要编译的库。你可以把它理解成给 AI 写的一份操作手册——当 AI 遇到某类任务时它会去读这份手册然后按照手册里的步骤执行。这个定义听起来简单但它解决了一个非常实际的问题。在没有 skills 之前你想让 AI 完成一个复杂任务要么把所有指令塞进一次对话的上下文里token 消耗巨大而且容易丢失细节要么依赖模型自身的通用能力结果不可控。Skills 的出现让专业能力可以像积木一样被组装、复用和分发。1.1 为什么skills会在短时间内爆发式流行这个问题的答案其实藏在热搜词里。你去看那些高频出现的词——claude agent skills、codex skills、agent skills 测试、skills 开发——它们指向的是同一个趋势AI 智能体正在从聊天工具变成生产力工具而 skills 是完成这个转变的关键基础设施。我自己的观察是这波流行有三个推动力。第一是模型能力到了临界点现在的模型已经足够聪明能理解复杂的结构化指令这在前两年是不成立的。第二是成本压力把专业指令做成可复用的模块比每次都在对话里重新描述要省太多 token。第三是生态需求开发者需要一个标准化的方式来分享和分发自己调教好的 agent 能力。提示如果你现在还在用每次对话都重新写一大段 prompt的方式使用 AI强烈建议花点时间了解一下 skills 的机制。这不是赶时髦而是实实在在能提升效率的东西。1.2 一个容易混淆的点skills 和 MCP 不是一回事我在社区里看到最多的误解就是把 skills 和 MCPModel Context Protocol混为一谈。这两个东西确实经常一起出现但它们解决的是完全不同的问题。MCP 解决的是AI 怎么连接外部工具和数据源的问题。比如让 AI 能读取你本地的文件、查询数据库、调用某个 API这些是 MCP 的职责。它更像是一个通信协议定义了 AI 和外部世界交互的标准方式。Skills 解决的是AI 在特定场景下应该怎么思考和行动的问题。它不负责连接任何东西只负责提供知识和流程。比如如何写一篇符合某平台调性的文章、如何做一次完整的代码审查、如何分析一份财报这些是 skills 的职责。打个比方MCP 是给 AI 装上了手和眼睛让它能操作东西、看到东西skills 是给 AI 装上了经验和判断力让它知道该怎么操作、先做什么后做什么。两者配合使用效果最好但概念上必须分清楚。2. Skills 的底层结构一个 skill 到底长什么样搞清楚了 skills 是什么接下来要解决的问题是一个 skill 在文件层面到底是什么形态这个问题不搞清楚后面所有的安装、开发、调试都是空中楼阁。我拆过十几个不同来源的 skills包括官方示例、社区分享的、以及自己写的它们的结构高度一致。核心就是一个目录里面至少包含一个描述文件通常还会有一些辅助资源。2.1 核心文件SKILL.md 的字段含义绝大多数 skills 的核心是一个名为SKILL.md的 Markdown 文件。这个文件通常由两部分组成开头的元数据frontmatter和正文内容。元数据部分用 YAML 格式写在两条---之间常见的字段包括字段名是否必填作用说明name必填skill 的唯一标识名通常用短横线连接的小写字母description必填一句话描述这个 skill 能做什么AI 靠这个判断是否调用version选填版本号方便管理和更新author选填作者信息社区分享时常用tags选填标签用于分类和搜索正文部分就是具体的指令内容。这里有个关键点很多人会忽略正文不是写给用户看的是写给 AI 看的。所以写法上要尽量结构化、明确、无歧义。我见过一些 skill 的正文写得像散文结果 AI 执行的时候经常跑偏就是因为指令不够明确。一个典型的SKILL.md结构大概是这样--- name: code-review-helper description: 对代码进行系统性审查输出结构化的问题清单和改进建议 version: 1.0.0 tags: [code, review, quality] --- ## 审查流程 1. 首先通读代码理解整体结构和业务意图 2. 按以下维度逐项检查 - 命名规范 - 错误处理 - 边界条件 - 性能隐患 - 安全隐患 3. 对每个发现的问题给出严重程度评级和修复建议 4. 最后输出一份汇总报告 ## 输出格式要求 使用表格呈现问题清单包含位置、问题描述、严重程度、建议2.2 辅助资源scripts、references 和 assets除了SKILL.md一个完整的 skill 目录里通常还会有几个子目录。这些不是必须的但合理使用能大幅提升 skill 的能力上限。scripts目录放的是可执行脚本。当 skill 需要做一些确定性计算或者文件操作时与其让 AI 去推理不如直接给一个脚本让它调用。这样既准确又省 token。比如一个处理 CSV 的 skill里面放一个 Python 脚本做数据清洗比让 AI 一步步推理要可靠得多。references目录放的是参考文档。比如一个写技术文档的 skill可以把公司的文档规范、术语表、历史优秀案例放在这里。AI 在执行任务时会参考这些内容输出质量会明显提升。assets目录放的是模板、图片、配置文件等静态资源。这个目录用得相对少一些但在需要固定输出格式的场景下很有用。注意辅助资源不是越多越好。每多一个文件AI 在调用时就要多读一份内容token 消耗和响应时间都会增加。我的经验是只放真正会被用到的资源能精简就精简。2.3 为什么这种结构能生效渐进式披露的设计哲学理解了文件结构还要理解背后的设计思想。Skills 这套机制最巧妙的地方在于渐进式披露progressive disclosure。具体来说AI 在启动时只会加载所有可用 skills 的name和description这两个字段。这部分的 token 消耗极小哪怕你装了几十个 skills也不会占用太多上下文。只有当 AI 判断某个 skill 和当前任务相关时它才会去读取那个 skill 的完整内容。这个设计解决了一个核心矛盾你希望 AI 知道很多东西但又不能让上下文被塞满。传统的做法是把所有知识都塞进 system prompt结果就是上下文又长又贵而且模型注意力被稀释效果反而下降。渐进式披露让 AI 按需加载既保证了知识的可及性又控制了成本。我自己实测下来这个机制的效果非常明显。之前我做一个项目需要 AI 同时具备代码审查、文档撰写、数据分析三种能力。如果全部写在一个 prompt 里大概要 3000 多 token而且经常出现串味的情况——写文档的时候突然开始审查代码。拆成三个 skills 之后每次只加载相关的那一个输出质量稳定了很多。3. 安装与配置从零跑通第一个 skill理论讲完了接下来是实操。这一部分我会把安装配置的完整流程走一遍包括我踩过的坑和对应的解决方案。3.1 环境准备不同平台的差异Skills 的安装方式取决于你使用的 AI 工具。目前主流的几个平台都有自己的 skills 管理机制但核心逻辑是相通的把 skill 目录放到指定的位置然后让工具能扫描到。以命令行工具为例常见的做法是通过包管理器安装。比如有些工具支持npx直接拉取和运行 skills 相关的命令。这里要提醒一句npx相关的操作在国内网络环境下经常会遇到下载失败的问题这个后面会专门讲。如果你用的是桌面端应用通常会有图形化的 skills 管理界面可以直接导入本地目录或者从市场安装。这种方式对新手最友好但灵活性稍差。还有一种方式是手动配置。把 skill 目录放到工具约定的路径下然后在配置文件里注册。这种方式最灵活适合需要精细控制的场景。3.2 目录放哪里路径选择的几个原则Skill 目录的存放位置看起来是个小问题但实际影响很大。我总结了几个原则第一不要放在系统临时目录里。有些工具重启后会清理临时目录你的 skills 就没了。我一开始图省事放在/tmp下面结果第二天全丢了重新配置花了半小时。第二路径里不要有中文和空格。这个问题在 Windows 上特别常见。有些工具在处理路径时对非 ASCII 字符支持不好会导致 skill 加载失败。建议统一用英文路径比如~/ai-skills/或者项目根目录下的.skills/。第三区分全局 skills 和项目级 skills。全局 skills 放在用户目录下所有项目都能用项目级 skills 放在项目目录下只对当前项目生效。我的做法是通用能力比如代码审查、文档撰写放全局项目特定的能力比如某个业务领域的知识放项目级。3.3 验证安装是否成功一个简单的测试方法装完之后怎么确认生效了最直接的方法是让 AI 执行一个只有该 skill 才能完成的任务。比如你装了一个生成 commit message的 skill就可以随便改一个文件然后让 AI 生成 commit message。如果输出格式符合 skill 里定义的规范说明加载成功了。如果 AI 还是按自己的通用方式输出那大概率是没加载上。排查的时候按这个顺序检查skill 目录路径对不对、SKILL.md的元数据格式对不对、工具的配置文件里有没有正确注册、工具有没有重启。这四个环节任何一个出问题都会导致 skill 不生效。提示很多工具都有 debug 模式或者日志输出能看到 skill 的加载过程。遇到问题先看日志比盲目猜测效率高得多。4. 开发自己的 skill从需求到落地用别人的 skill 只是第一步真正能发挥价值的是根据自己的需求开发 skill。这一部分我会完整讲一遍开发流程包括怎么设计、怎么写、怎么测试。4.1 什么样的任务适合做成 skill不是所有任务都值得做成 skill。我踩过的坑是一开始兴致勃勃地把所有常用操作都做成了 skill结果发现大部分根本用不上反而增加了维护负担。判断一个任务是否适合做成 skill我总结了一个简单的标准这个任务是否会被重复执行且执行过程有明确的步骤和标准。适合做成 skill 的典型场景包括代码审查每次都要按同样的维度检查、文档撰写有固定的格式和风格要求、数据分析有标准的处理流程、内容生成有明确的调性和结构要求。不适合的场景包括一次性的探索性任务、需要大量人工判断的任务、结果没有明确标准的任务。这些做成 skill 反而会限制 AI 的发挥。4.2 写 SKILL.md 的实操技巧写SKILL.md是整个开发过程中最关键的一步。我写过十几个 skill总结了几条实用技巧。description 字段要精准。这个字段决定了 AI 什么时候会调用你的 skill。写得太宽泛会导致 skill 被频繁误调用写得太窄又会导致该用的时候用不上。我的经验是description 里要包含做什么和什么时候用两个信息。比如对 Python 代码进行静态审查适用于提交前的代码质量检查就比代码审查工具要好得多。正文要用指令式语言。不要写这个 skill 可以帮助你……而要写按以下步骤执行……。AI 对指令式语言的理解准确度明显更高。步骤要具体到可执行。检查代码质量这种描述太模糊AI 不知道具体检查什么。检查以下五项命名规范、错误处理、边界条件、性能隐患、安全隐患就明确多了。给出输出格式示例。如果 skill 的输出有固定格式要求最好在正文里给一个完整的示例。AI 模仿示例的能力很强这比用文字描述格式要有效得多。4.3 测试与迭代怎么知道 skill 写得好不好Skill 写完不是终点测试和迭代才是。我的做法是准备一组测试用例覆盖典型场景和边界场景每次修改 skill 后都跑一遍。测试的时候重点关注三个指标触发准确率该调用的时候有没有调用、执行准确率执行过程是否符合预期、输出质量结果是否达到要求。如果触发准确率低问题通常出在 description 上需要调整措辞。如果执行准确率低问题通常出在正文的指令不够明确需要细化步骤。如果输出质量不稳定可能是缺少示例或者约束条件不够。我一般会迭代三到五轮直到三个指标都稳定下来。这个过程听起来繁琐但一次投入之后后面每次使用都能受益。5. 常见问题排查那些让人抓狂的坑这一部分是我在实际使用中遇到的各种问题汇总按出现频率排序。如果你正在被某个问题困扰可以直接跳到对应的小节。5.1 npx 相关命令执行失败这是国内用户遇到最多的问题。npx在执行时会去远程仓库拉取包网络不通畅的时候就会卡住或者报错。排查思路是这样的先确认基础网络是否正常然后检查 npm 的源配置。如果源配置有问题可以切换到国内镜像源。具体操作是修改 npm 的 registry 配置指向国内的镜像地址。还有一个常见原因是缓存问题。npx会缓存下载过的包如果缓存损坏也会导致执行失败。这时候可以清理缓存后重试。如果以上都试过还是不行可以考虑手动下载包然后本地执行。虽然麻烦一点但能绕过网络问题。5.2 skill 加载了但不生效这个问题比网络问题更让人头疼因为没有任何报错就是静默失效。我的排查清单是这样的首先确认文件路径和文件名是否完全正确SKILL.md的大小写敏感写成skill.md在某些系统上就找不到。然后检查元数据格式YAML 对缩进和符号很敏感一个多余的空格都可能导致解析失败。接着确认工具的配置文件里有没有正确注册这个 skill。最后重启工具有些工具需要重启才能扫描到新的 skill。如果以上都没问题可以尝试把 skill 简化到最小可运行状态然后逐步加回内容定位是哪部分导致的失效。5.3 skill 之间互相干扰当你装了多个 skills 之后可能会遇到它们互相干扰的情况。典型表现是AI 调用了错误的 skill或者把多个 skill 的指令混在一起执行。这个问题的根源通常是 description 之间的边界不清晰。比如你有一个写技术文档的 skill 和一个写产品文档的 skill如果两个 description 都写得很宽泛AI 就分不清什么时候该用哪个。解决方案是让每个 skill 的适用范围尽可能互斥。在 description 里明确写出适用于什么场景和不适用于什么场景。必要时可以在正文里加一句如果任务属于 XX 类型请使用其他 skill。5.4 输出格式不稳定有时候 skill 明明定义了输出格式但 AI 执行时就是不按格式来。这个问题通常有三个原因。一是格式定义不够明确。用文字描述格式容易产生歧义最好直接给一个完整的输出示例。二是约束不够强。可以在正文里用加粗或者明确的必须、禁止等词来强化约束。三是任务本身太复杂AI 在处理过程中忘记了格式要求。这时候可以考虑把任务拆分成多个步骤每步都重申格式要求。6. 进阶玩法让 skills 真正融入工作流掌握了基础的安装和开发之后可以开始考虑一些进阶玩法。这部分内容适合已经用过一段时间 skills、想进一步提升效率的读者。6.1 skill 的组合与编排单个 skill 的能力是有限的真正的威力在于组合。比如你可以设计一个周报生成的 skill它内部会依次调用数据汇总、内容撰写、格式排版三个子 skill。实现组合的方式有两种。一种是在一个 skill 的正文里直接引用其他 skill让 AI 按顺序执行。另一种是通过工具本身的编排能力把多个 skill 串成一条流水线。我个人更推荐第一种方式因为它更灵活AI 可以根据实际情况调整执行顺序。第二种方式适合流程非常固定的场景。6.2 版本管理与团队协作当 skills 数量多起来之后版本管理就成了问题。我的做法是把 skills 目录纳入 Git 管理每个 skill 的修改都走正常的代码审查流程。这样做有几个好处可以追溯每个 skill 的修改历史方便回滚团队成员可以共享和复用 skills可以通过分支管理不同环境的 skill 版本。团队协作时要注意的是skill 的命名和 description 要有统一的规范否则很容易出现重复或者冲突。我们团队的做法是给每个 skill 加前缀比如team-开头的是通用 skillproj-开头的是项目专用 skill。6.3 性能优化减少 token 消耗Skills 用多了之后token 消耗会明显上升。优化方向主要有两个减少加载量和减少执行量。减少加载量的关键是精简SKILL.md的内容。把不常用的细节移到references目录只在需要时才读取。description 也要尽量简短因为这部分是每次都会加载的。减少执行量的关键是提高一次成功率。如果 AI 第一次执行就对了就不需要反复调整token 消耗自然就降下来了。这需要在 skill 开发阶段多下功夫把指令写得足够明确。我实测下来经过优化的 skill 比未优化的版本token 消耗能降低 40% 左右。这个数字在长期使用中非常可观。7. 我个人的一些经验和判断写了这么多最后分享几点我自己的体会不算总结就是一些零散的经验。不要追求 skill 的数量。我见过有人装了上百个 skills结果大部分从来没用过反而拖慢了工具的运行速度。真正有价值的 skill 可能就五到十个把这几个人打磨好比装一堆用不上的强得多。skill 的质量比数量重要得多。一个精心设计的 skill能顶十个粗糙的。判断质量的标准很简单用它执行任务看结果是否稳定、是否符合预期。如果每次结果都不一样那这个 skill 就需要继续打磨。保持学习的心态。Skills 这个领域变化很快新的工具、新的最佳实践层出不穷。我自己的做法是定期逛社区看看别人在用什么、怎么用。很多时候一个困扰我很久的问题别人早就有了成熟的解决方案。从解决自己的实际问题出发。不要为了做 skill 而做 skill。先找到自己工作中真正重复、真正耗时的环节然后针对性地开发 skill。这样的 skill 才有生命力才会被持续使用和优化。注意安全边界。开发 skill 的时候要清楚它能做什么、不能做什么。特别是涉及文件操作、数据处理的 skill一定要有明确的边界和错误处理。我见过因为 skill 里没有做输入校验导致 AI 误删文件的案例这个教训很深刻。Skills 这套机制目前还在快速演进中现在的很多做法过几个月可能就过时了。但底层的设计思想——渐进式披露、模块化、按需加载——这些是相对稳定的。理解了这些不管工具怎么变你都能快速适应。