1. 从“skills”这个热词说起它到底指什么最近一段时间不管是在技术社区还是各类开发者群组里“skills”这个词出现的频率高得有点反常。如果你只是偶尔刷到可能会以为它说的是“技能”这个通用词但结合 Google Cloud、AI agents、GKE、Genkit 这些关联词一起看就会发现它指向的是一个非常具体的东西——AI agent 的能力扩展单元。简单来说skills 就是给 AI agent 加装的一个个“技能包”。一个 agent 本身可能只会聊天、只会调用基础模型但当你给它挂上不同的 skills 之后它就能做代码审查、能写论文、能做分镜、能自动挖洞、能操作云资源。你可以把它理解成给一个刚入职的实习生配工具箱人还是那个人但工具箱里装了什么决定了他能干什么活。这个概念的爆发和 Claude agent skills 的推出有直接关系。它把“agent 能力扩展”这件事从“写一堆胶水代码”变成了“安装一个 skill 包”门槛一下子降下来了。于是你能看到热词里出现“claude 国内安装 skills 官方市场”“skills 安装包下载”“skills 下载平台有哪些”这类搜索——大家都在找怎么装、去哪装、装哪个好用。这篇文章要解决的就是围绕 skills 这个核心把它的本质原理、安装机制、开发方法、选型思路、实战踩坑讲透。不管你是刚听说这个词想入门还是已经在用 codex skills、claude agent skills 想深入都能从下面这些内容里找到能直接上手的东西。我会尽量用从业者之间聊天的口吻把那些文档里不会写的细节摊开讲。2. skills 的本质它不是插件是“能力契约”2.1 为什么 skills 和传统插件不是一回事很多人第一次接触 skills会下意识把它类比成浏览器插件或者 IDE 插件。这个类比有一半对但另一半会把你带偏。插件通常是代码级扩展——你写一段程序挂到宿主程序的生命周期里宿主调用你的代码。而 skills 的核心不是代码是一份结构化的能力描述。我用一个生活化的类比来解释。传统插件像是你给手机装了一个 AppApp 里有自己的逻辑、自己的界面、自己的数据。而 skill 更像是你给一个助理写了一份工作说明书什么情况下该做这件事、做这件事需要哪些信息、做完之后输出成什么格式、遇到什么情况要停下来问人。助理也就是 agent读的是这份说明书然后用自己的通用能力去执行。这个区别带来的直接后果是skill 的编写门槛远低于插件。你不需要精通宿主程序的 API不需要处理复杂的生命周期钩子你只需要把“这件事该怎么做”讲清楚。这也是为什么热词里会出现“今天学会了 skills打开新世界”这种表达——因为它真的让非专业开发者也能给 agent 加能力。2.2 一个 skill 的最小构成虽然不同平台Claude、Codex、Genkit 等的 skill 格式有差异但拆开看核心要素是共通的。我把它归纳成下面这张表你可以对照自己手上的 skill 文件看构成要素作用常见形式触发描述告诉 agent 什么时候该用这个 skill自然语言描述 关键词输入定义明确执行需要哪些参数或上下文字段列表、类型说明执行指令核心步骤agent 按此操作分步骤的自然语言指令输出规范规定结果以什么格式返回模板、schema、示例边界条件什么情况不该做、该停下来否定条件、异常处理说明你会发现这里面没有一行是必须写代码的。执行指令可以是纯自然语言输出规范可以是一个 Markdown 模板。这就是 skills 的精髓用描述代替编程用契约代替接口。提示很多人写 skill 失败不是因为指令不够详细而是因为触发描述写得太模糊。agent 不知道该在什么时候调用它再好的执行指令也白搭。这一点后面会专门展开。2.3 skills 和 agent 的关系能力是挂载的不是内置的理解 skills还要理解它和 agent 的挂载关系。一个 agent 的“基础智力”来自底层大模型但它的“专业能力”来自挂载的 skills 集合。这带来两个重要特性。第一同一个 agent 可以通过换 skills 集合变成完全不同的角色。今天挂上代码审查 skills它就是代码审查员明天换成论文写作 skills它就是学术助手。热词里“codex 写论文的 skills”和“自动挖洞 skills”能同时存在就是因为这个机制。第二skills 是可以组合的。一个复杂任务往往需要多个 skill 协同。比如“自动挖洞”这个场景可能需要一个 skill 负责信息收集一个负责漏洞识别一个负责报告生成。它们之间通过 agent 的调度串联起来。这就引出了后面要讲的 skill 编排问题。3. 安装 skills 的几条路官方市场、手动导入与包管理3.1 官方市场安装最省事但最受限对于 Claude agent skills 这类有官方市场的平台安装是最简单的。通常的流程是在 agent 的配置界面找到 skills 市场搜索你需要的 skill点击安装然后 agent 会自动把它挂载到当前会话或全局配置里。这条路适合绝大多数普通用户。热词里“claude 国内安装 skills 官方市场”之所以被频繁搜索是因为官方市场虽然方便但访问和账号体系有时会成为门槛。这里我不展开讲网络层面的东西只提醒一点如果你在官方市场里搜不到某个 skill不代表它不存在很可能只是没上架需要走手动导入。官方市场安装的另一个限制是版本锁定。市场里的 skill 是平台审核过的版本更新节奏由平台控制。如果你需要某个 skill 的最新特性或者想改里面的指令就得走手动路线。3.2 手动导入把 skill 文件放进指定目录手动导入是 skills 生态里最通用、最不依赖平台的方式。基本逻辑是skill 本质上是一个文件夹或一个描述文件你把它放到 agent 约定的 skills 目录下agent 启动时扫描这个目录就能识别并加载。以常见的目录约定为例结构大致是这样skills/ ├── code-review/ │ ├── skill.md # 核心描述文件 │ └── examples/ # 可选示例输入输出 ├── paper-writing/ │ └── skill.md └── recon/ └── skill.md每个skill.md里写的就是上一节说的那套契约。手动导入的好处是完全可控你可以改指令、加示例、调触发条件。坏处是没有自动更新skill 升级了得自己重新拉。注意不同平台对目录名和文件名的约定不一样。有的要求文件名必须是SKILL.md大写有的要求放在.agent/skills/下。装之前一定先看平台的目录规范放错位置 agent 是扫不到的而且通常不会报错只会静默忽略——这是新手最容易踩的坑。3.3 包管理式安装适合批量与团队协作当 skills 数量多起来或者需要在团队里统一管理时手动一个个放文件就不现实了。这时候会用到包管理式的思路把 skills 打包成可分发单元通过命令行工具安装、更新、卸载。热词里“reasonix 如何安装新 skills”“skills 安装包下载”反映的就是这类需求。包管理式安装通常提供这些命令# 安装一个 skill 包 skills install code-review # 从指定源安装 skills install ./local-skills/recon # 列出已安装 skills list # 更新全部 skills update这种方式的优势是可复现。团队里每个人执行同样的安装命令得到的 skills 集合是一致的。配合版本号还能做到“锁定到某个版本”避免某天 skill 更新后行为突变导致线上问题。3.4 三种安装方式怎么选我把三种方式的适用场景整理成表你可以直接对号入座安装方式适合谁优点缺点官方市场个人用户、快速试用一键安装、有审核版本受限、可能搜不到手动导入需要定制、调试 skill完全可控、可改指令无自动更新、易放错目录包管理团队、多 skill 场景可复现、易批量管理需要额外工具链我的建议是先用官方市场跑通一个 skill理解它的工作方式然后手动导入一个改一改理解它的结构最后在团队场景里上包管理。这个顺序能让你每一步都踩在理解上而不是盲目装一堆用不上的 skill。4. 开发一个自己的 skill从“想让它干什么”到“写清楚怎么干”4.1 先想清楚触发条件再想执行步骤大部分人开发 skill 的顺序是错的。他们一上来就写“第一步做什么、第二步做什么”结果写完发现 agent 根本不在正确的时机调用它。正确的顺序是先定义触发再定义执行。触发条件要回答一个问题在什么情况下agent 应该想到用这个 skill这个描述要具体到能被匹配。比如“当用户要求审查代码时”就太宽泛“当用户提供了一段代码并询问潜在问题时”就具体得多。更好的做法是同时给出正向触发词和反向排除条件。举个例子一个代码审查 skill 的触发描述可以这样写当满足以下条件时使用本 skill - 用户提供了完整的函数或文件级代码 - 用户询问代码质量、潜在 bug、性能问题 - 用户明确要求 review 以下情况不要使用 - 用户只是问语法问题 - 代码片段少于 5 行 - 用户要求的是重构而非审查这个“不要使用”的部分很多人会忽略但它恰恰是减少误触发的关键。4.2 执行指令的写法像给新人写 SOP执行指令是 skill 的主体。写它的心态应该是你在给一个聪明但完全不了解你业务的新人写操作手册。他懂通用逻辑但不懂你的具体规矩所以每一步都要交代清楚“做什么”和“为什么”。一个常见的错误是写得太抽象比如“分析代码并给出建议”。这句话 agent 执行起来会非常随机每次输出都不一样。正确的写法是拆成可执行的步骤并且规定每步的输出1. 通读代码识别出所有函数和它们的调用关系 2. 对每个函数检查以下三类问题 - 边界条件空值、越界、类型不匹配 - 资源管理是否有未释放的资源 - 并发安全共享状态是否有保护 3. 对每个发现的问题输出 - 位置函数名 行号范围 - 问题类型 - 严重程度高/中/低 - 修复建议给出具体代码 4. 最后按严重程度排序高优先级在前这样写出来的 skill输出是稳定的、可预期的。这也是为什么好的 skill 看起来像一份结构化的检查清单而不是一段散文。4.3 输出规范用模板锁死格式输出规范决定了 skill 返回结果的样子。如果你希望结果能被后续流程消费比如被另一个 skill 读取或者被程序解析就必须用结构化模板锁死格式。Markdown 表格、JSON schema、固定字段的列表都是常见选择。关键是要给出一个完整的示例让 agent 照着填。比如输出格式严格按此模板 ## 审查结果 | 位置 | 类型 | 严重程度 | 建议 | |------|------|---------|------| | func_name:10-15 | 边界条件 | 高 | 增加空值检查 | ## 总结 共发现 N 个问题其中高优先级 M 个。有了这个模板agent 就不会自由发挥输出的一致性会大幅提升。这一点在“agent skills 测试”这个热词背后其实是个核心痛点——测试 skill 好不好用很大程度上就是看它的输出稳不稳定。4.4 给 skill 加示例few-shot 比长篇解释更有效如果你发现某个 skill 怎么调都不对先别急着加更多指令试试加示例。在 skill 文件里放一两组“输入 → 期望输出”的样例效果往往比写五百字解释还好。这是因为大模型对示例的敏感度远高于抽象描述。你告诉它“输出要简洁”它可能理解成各种样子但你给它一个简洁输出的例子它就能准确模仿。示例的放置位置也有讲究。通常放在执行指令之后、输出规范之前作为“参考样例”。如果平台支持还可以把示例单独放在examples/目录里让 agent 按需读取。5. skills 选型与组合别装一堆用不上的5.1 按任务链路选而不是按热度选热词里“skills 推荐”“skills 大全”“codex 好用的 skills”说明大家都在找“该装哪些”。我的经验是不要按热度装要按你的任务链路装。具体做法是先把你日常用 agent 做的事列出来画成一条条链路。比如你是个做安全测试的链路可能是信息收集 → 资产识别 → 漏洞扫描 → 报告生成。然后针对每个环节找对应的 skill。这样装出来的集合是刚好覆盖你工作流的不会有一堆闲置的。反过来如果你看到“自动挖洞 skills”很火就装上但你的工作根本不涉及这个环节那它只会增加 agent 的决策负担甚至在不该触发的时候误触发。5.2 skill 之间的编排谁先谁后谁调谁当你有多个 skill 时编排就成了关键问题。编排要解决两件事顺序和数据传递。顺序上通常有串行和并行两种。串行就是 A 做完交给 B适合有依赖关系的链路。并行是 A 和 B 同时做适合互相独立的子任务。大部分 agent 平台支持在 skill 描述里声明依赖比如“本 skill 需要先执行 recon skill 的输出”。数据传递上要确保上游 skill 的输出格式能被下游 skill 读取。这就是为什么前面强调输出规范要用结构化模板——如果上游输出的是散文下游 skill 根本没法解析。提示编排最容易出问题的地方是中间结果的格式。我踩过的坑是上游 skill 输出了一段自然语言总结下游 skill 期望的是 JSON结果下游直接报错或者胡乱解析。解决办法是在上游 skill 的输出规范里明确写“以 JSON 格式输出字段包括……”。5.3 什么时候该自己写什么时候该用现成的不是所有需求都值得自己写 skill。判断标准很简单这个能力是不是你的核心差异化如果是通用能力比如“总结一段文字”“翻译”现成的 skill 一抓一大把直接用就行没必要自己写。如果是你业务特有的比如“按我们公司的代码规范审查”那现成 skill 肯定不满足必须自己写。还有一个中间地带现成 skill 覆盖了 80%但差 20%。这时候可以基于现成 skill 改而不是从零写。手动导入方式在这里就体现出价值了——你把现成 skill 的文件拿过来改掉那 20% 的指令就是一个贴合你需求的 skill。6. 实战踩坑那些文档里不会写的细节6.1 触发描述写太宽agent 到处乱用这是我见过最多的坑。有个朋友写了个“文档整理”skill触发描述写的是“当用户需要处理文档时”。结果 agent 在用户只是问“这个文档讲了啥”的时候也去调用它把简单的问答变成了复杂的整理流程体验极差。修复方法就是前面说的加反向排除条件。把“不要使用”的情况列清楚尤其是那些看起来相关但实际不该触发的场景。这个清单可以随着你发现误触发的情况不断补充。6.2 指令里的“尽量”“适当”是灾难自然语言里我们习惯说“尽量简洁”“适当展开”但在 skill 指令里这些词是灾难。agent 对“尽量”的理解每次都不一样导致输出忽长忽短。正确的做法是量化。“简洁”改成“不超过 3 句话”“适当展开”改成“每个要点展开 2-3 句”。数字是确定的agent 执行起来就稳定。6.3 skill 更新后行为突变如果你用的是官方市场或包管理的 skill某天更新后可能发现行为变了。这不是 bug是 skill 的作者改了指令。对于生产环境依赖的 skill一定要锁版本。包管理方式通常支持版本锁定官方市场如果支持也尽量锁。手动导入的 skill 反而没这个问题因为文件在你手里不主动改就不会变。这也是为什么有些团队宁愿手动维护 skill 目录也不走自动更新。6.4 测试 skill 不能只看一次输出“agent skills 测试”这个热词背后很多人测试 skill 的方法是跑一次看输出还行就上线了。这是不够的。因为 agent 有随机性同一次输入跑两次结果可能不同。我的做法是同一个 skill 至少跑 5 次不同的输入覆盖正常情况、边界情况、异常情况。重点看两件事一是输出格式是否稳定二是触发时机是否准确。如果 5 次里有 1 次格式跑偏那这个 skill 就还需要打磨。6.5 别把 skill 当万能药最后说一个心态上的坑。skills 很强大但它不是万能的。有些任务用 skill 做反而不如直接写一段代码或者用传统工具。判断标准是这个任务是不是需要“理解”和“判断”如果需要skill 合适如果只是确定性的数据处理写代码更靠谱。我见过有人非要用 skill 去做正则替换结果 agent 每次替换的规则都不完全一样还不如一行sed命令。工具选型要务实别为了用 skills 而用 skills。7. 从 skills 生态看 agent 能力的未来走向skills 这个概念的流行其实反映了一个更大的趋势agent 的能力正在从“模型内置”走向“外部挂载”。以前你想让 agent 会做某件事得等模型升级或者自己微调。现在你写个 skill 挂上去就行迭代速度完全不是一个量级。这个趋势带来的直接结果是skill 的生态会越来越像今天的 App 生态。有官方市场有第三方分发有免费有付费有通用有垂直。热词里“skills 下载平台有哪些”“skills 大全”就是生态初期的典型搜索——大家在找入口。对开发者来说这意味着两件事。第一写 skill 可能成为一个新的技能方向。就像当年会写 App 的人吃到了移动互联网红利会写高质量 skill 的人可能会在 agent 时代有优势。第二skill 的质量会分化。现在很多 skill 是随手写的能用但不好用。未来会出现一批精心打磨的、针对特定场景深度优化的 skill这些才是真正有价值的。对普通用户来说最实际的影响是你给 agent 装什么 skill决定了它对你有多大用。同一个 agent装对了 skill 是得力助手装错了就是添乱。所以花点时间理解 skills 的机制、学会挑选和组合是值得的。我自己现在的做法是维护一个精简的 skill 集合每个 skill 都经过至少 5 次测试定期清理用不上的。这个集合不大但每个都能在正确的时机稳定工作。比起装几十个 skill 然后被误触发搞得焦头烂额这种“少而精”的策略在实际使用中舒服得多。如果你刚开始接触 skills不妨也从一两个核心场景开始跑通了再扩展别一上来就追求“大全”。