1. 从skills这个热词说起它到底在解决什么问题如果你最近在折腾 Claude Code、Codex 或者各类 agents 工具大概率会在社区里反复刷到skills这个词。有人把它翻译成技能有人叫它能力包还有人直接说它是给 AI 装插件。这些说法都对但都不够准确。我自己的理解是skills 是一套把人类经验结构化封装、让 agent 能够按需调用的机制。它解决的核心痛点非常具体——大模型本身很聪明但它不知道你的项目规范、你的团队约定、你的私有工具链怎么用。每次对话你都要重复交代一遍背景效率极低而且交代得还不一定完整。skills 的出现本质上是把提示词工程从一次性对话里抽离出来变成可复用、可版本管理、可组合的资产。你可以把它想象成给一个新入职的同事写的岗位操作手册手册里写清楚什么场景下该做什么、用哪个工具、遵循什么规范、遇到什么情况要停下来问人。区别在于这份手册是写给 agent 看的而且 agent 会在需要的时候自动翻阅对应章节而不是从头读到尾。这个机制之所以在 Claude Code、Codex 这类工具里特别火是因为它们本身就是能动手干活的 agent不只是聊天。它们能读写文件、执行命令、调用外部服务。能力越强越需要约束和引导否则它就会用自己那套通用逻辑去处理你的专业问题结果往往差强人意。skills 就是那个约束 引导的载体。适合读这篇内容的人大概分三类第一类是刚接触 Claude Code 或 Codex听说 skills 很香但不知道从哪下手的新手第二类是已经在用 agent 干活但每次都要重复贴大段提示词、想找更优雅方案的中级用户第三类是想自己开发 skills、把它集成到团队工作流里的进阶玩家。不管你在哪一层下面这些内容我都会尽量讲到能直接上手。2. skills 的底层逻辑为什么它不是简单的提示词模板2.1 从一次性提示到按需加载的知识单元大多数人第一次接触 skills会下意识觉得这不就是把提示词存成文件吗。如果你只是把一段 prompt 存进 markdown那确实没什么新鲜的。skills 真正的价值在于触发机制和加载时机。传统做法是你把一大段系统提示塞进对话开头模型每次都要把这坨内容全部读一遍。内容短还好一旦你的规范文档写到几千字token 消耗先不说模型还容易注意力涣散——前面读的东西到后面就忘了。skills 的设计思路完全不同它把知识拆成一个个独立单元每个单元有自己的名称、描述、触发条件。agent 在接到任务时先看任务描述判断这个任务需不需要调用某个 skill需要才加载对应内容。不需要的 skill 根本不进上下文。这个机制带来的直接好处有三个。第一是上下文干净模型注意力集中在真正相关的信息上。第二是可组合一个复杂任务可以串联多个 skill比如先调用代码规范检查再调用单元测试生成。第三是可维护某个规范变了你只改对应的 skill 文件不用去动那一大坨系统提示。2.2 skill 的典型结构描述、触发、内容三段式虽然不同工具对 skill 的具体格式要求略有差异但核心结构是相通的。我把它归纳成三段式元信息metadata包括 skill 的名字、一句话描述、适用场景。这部分是给 agent 看目录用的决定它要不要加载这个 skill。触发条件trigger什么情况下该用这个 skill。可以是关键词匹配也可以是任务类型判断。写得越具体误触发越少。主体内容body真正给 agent 看的操作指南。包括步骤、规范、示例、注意事项、边界条件。我见过很多人写 skill 只写主体内容元信息和触发条件随便糊弄。结果就是 agent 要么该用的时候不用要么不该用的时候乱用。元信息和触发条件的质量直接决定 skill 的可用性这部分后面我会专门讲怎么写。2.3 为什么 Claude Code 和 Codex 都押注 skills这两个工具虽然定位不同但在 skills 这件事上思路高度一致。Claude Code 更偏向终端里的全能助手Codex 更偏向代码生成与补全但它们都面临同一个问题通用能力很强专业能力很弱。一个通用 agent 不知道你们公司用的是什么代码风格、什么提交规范、什么测试框架。它也不知道你个人的偏好比如你喜欢用函数式还是面向对象、注释写中文还是英文。这些信息如果每次都靠对话交代用户体验极差。skills 就是把这些个性化知识沉淀下来的容器。从产品角度看skills 还有一个战略意义它把生态开放出来了。官方不可能预置所有场景的 skill但用户可以自己写、可以分享、可以形成市场。这就从单机工具变成了平台。热词里出现的skills 推荐claude 国内安装 skills 官方市场find skills这些搜索本质上都是用户在找别人写好的、我能直接用的 skill。3. 手把手写第一个 skill从零到能跑通3.1 环境准备Claude Code 与 Codex 的安装差异在写 skill 之前你得先把宿主工具装好。Claude Code 和 Codex 的安装路径不太一样我分别说一下我实测过的流程。Claude Code 的安装官方推荐用 npm 全局安装。前提是你机器上有 Node.js 环境版本建议 18 以上。装完之后用claude命令启动第一次会引导你登录。Windows 用户注意如果你在 PowerShell 里遇到执行策略报错需要先调整执行策略这个坑很常见。另外热词里提到的claude code windowsclaude code for vs codevscode 配置 claude code说明很多人是在 VS Code 里用这个后面单独讲。Codex 的安装相对简单一些官方有独立的安装包也有 npm 方式。热词里codex 安装包codex 下载codex 官网下载codex 安装教程codex 安装 csdn这些搜索量很大说明安装环节确实卡住了不少人。我的建议是优先走官方渠道第三方教程里的安装包来源不明容易出问题。装完之后用codex命令验证能正常进入交互界面就算成功。提示安装过程中如果遇到网络相关的报错先检查你的包管理器配置和本地环境变量不要盲目照搬网上的一键脚本。很多脚本会改你的全局配置后患无穷。3.2 skill 文件的目录约定与命名规范不同工具对 skill 存放位置有约定。Claude Code 一般放在项目根目录下的特定文件夹里或者用户级配置目录里。Codex 类似。我建议的做法是项目相关的 skill 放项目里个人通用的 skill 放用户级目录。这样团队协作时项目 skill 可以随代码一起提交新人拉下来就能用。命名上我踩过的坑是用了中文名和空格。虽然有些工具能识别但跨平台、跨工具时容易出问题。统一用英文小写加连字符比如code-review、commit-message、api-design。名字要能一眼看出用途别用skill1、my-skill这种。目录结构上一个 skill 一个文件夹里面至少有一个主文件通常是 markdown复杂一点的可以带辅助文件比如示例代码、配置模板。这样打包分享的时候直接压缩文件夹就行。3.3 元信息怎么写才能让 agent 正确触发这是最容易被低估的部分。元信息里的描述本质上是给 agent 做检索匹配用的。你写得越贴近 agent 的判断逻辑触发越准。我的经验是描述里要包含三类信息做什么、什么时候用、不适用什么场景。举个例子一个生成提交信息的 skill描述可以这么写做什么根据代码改动生成符合规范的 git commit message什么时候用用户要求提交代码、或者明确说帮我写提交信息时不适用不用于生成 PR 描述不用于代码审查把不适用也写清楚能大幅减少误触发。我早期写的 skill 就是因为没写边界agent 在代码审查的时候也去调生成提交信息结果输出一堆无关内容。触发条件这块如果你的工具支持关键词或正则匹配尽量写得具体。比如当用户消息包含提交、commit、git 且涉及代码改动时触发比笼统的涉及 git 操作时触发要准得多。3.4 主体内容的组织步骤、示例、边界一个都不能少主体内容是 skill 的肉。我见过写得好的 skill读起来像一份精心编写的 SOP写得差的就是一段干巴巴的说明。我的组织方式是四段目标说明、操作步骤、正反示例、边界与异常。目标说明用一两句话讲清楚这个 skill 要达成什么结果。操作步骤要编号每步说清楚做什么、为什么、注意什么。正反示例特别重要——给一个正确输出的例子再给一个错误输出的例子agent 对对比的理解能力很强看了反例就知道要避开什么。边界与异常部分列出常见的不适用场景和出错处理方式。举个例子一个代码审查skill 的主体可以这么写目标是发现代码中的潜在问题并给出修改建议步骤是先看整体结构再看细节先看逻辑再看风格正例是第 15 行的循环边界可能越界建议改为而非反例是这段代码写得不好太笼统边界是不审查第三方库代码不审查自动生成的代码。4. 让 skill 真正好用的几个关键细节4.1 触发精度避免该用不用和不该用乱用触发精度是 skill 实用性的生命线。我实测下来影响触发精度的因素主要有三个描述的清晰度、触发条件的宽窄、以及 skill 之间的重叠度。描述清晰度前面讲过了。触发条件这块我的建议是宁可窄一点也不要宽。窄了顶多是该用的时候没自动用用户手动指定一下就行宽了就是到处乱触发反而干扰正常任务。skill 之间的重叠度也要注意如果你有两个 skill 都涉及代码质量agent 可能不知道该调哪个。解决办法是在描述里明确区分比如一个叫代码风格检查一个叫逻辑缺陷排查。还有一个技巧是给 skill 加优先级或互斥标记。有些工具支持这个不支持的话可以在描述里写当 X skill 也适用时优先使用本 skill。4.2 内容粒度一个 skill 只干一件事新手最容易犯的错是把一堆相关但不相同的任务塞进一个 skill。比如写一个前端开发skill里面既有组件规范、又有样式约定、还有构建配置。结果就是 agent 加载了一大坨内容但真正用到的只有一小部分上下文被浪费注意力被分散。一个 skill 只干一件事这是铁律。组件规范就单独一个 skill样式约定单独一个构建配置单独一个。需要组合的时候让 agent 自己串联调用。这样每个 skill 都短小精悍加载快、理解准、维护易。粒度细了之后skill 的数量会变多这时候命名和分类就很重要。我一般按领域-动作来命名比如frontend-component、frontend-style、frontend-build一眼就能看出归属。4.3 版本管理skill 也要进 git很多人写 skill 就是本地改改改完就用从不版本管理。这是大忌。skill 本质上是你的经验资产它会随着项目演进不断调整。没有版本管理你改坏了都回不去。我的做法是项目级 skill 跟项目代码一起进 git个人级 skill 单独建一个仓库。每次修改写清楚 commit message说明改了什么、为什么改。团队协作时skill 的变更可以走 code review确保质量。另外skill 的变更最好有变更日志。在 skill 文件末尾加一个简单的 changelog记录每次修改的时间和原因。这样别人用你的 skill 时能知道它经历过什么。4.4 测试 skill怎么验证它真的按预期工作skill 写完不是就完事了得测。我一般用三类测试正向测试、反向测试、边界测试。正向测试是给一个明确该触发 skill 的任务看它是否触发、输出是否符合预期。反向测试是给一个明确不该触发的任务看它是否误触发。边界测试是给一些模棱两可的任务看它的判断是否合理。测试的时候要记录结果尤其是失败的案例。失败的案例往往能暴露描述或触发条件的问题。我自己的习惯是建一个测试用例文件每次改完 skill 就跑一遍确保没有回归。热词里agent skills 测试这个搜索说明已经有人意识到测试的重要性了。这块目前还没有特别成熟的工具主要靠手动但值得投入时间。5. 进阶玩法skills 的组合、分享与生态5.1 skill 串联让 agent 自己编排工作流单个 skill 能力有限真正的威力在于组合。比如一个新功能开发的完整流程可以拆成需求分析 skill、接口设计 skill、代码实现 skill、测试生成 skill、提交信息 skill。agent 接到开发 XX 功能的任务后自己判断需要哪些 skill按顺序调用。这种串联不需要你显式编排只要每个 skill 的描述和触发条件写清楚agent 自己会规划。当然你也可以在某个总控 skill 里写明推荐流程引导 agent 按你的思路走。我实测下来串联效果好的前提是skill 之间的接口要清晰。比如接口设计skill 的输出格式要能被代码实现skill 直接消费。这需要你在写 skill 的时候就考虑上下游衔接。5.2 团队协作把 skill 变成团队规范载体skills 在团队场景下的价值被严重低估了。它其实是团队规范的最佳载体。传统的规范文档写在 wiki 里没人看写在代码注释里太零散。写成 skillagent 每次干活都会自动遵循等于把规范强制执行了。我们团队现在的做法是所有代码规范、提交规范、审查规范都写成 skill新人入职第一件事就是装好这些 skill。他写代码的时候agent 会自动按团队规范来省去了大量口头交代和文档阅读。团队 skill 的维护要有专人负责定期 review 和更新。规范变了skill 要同步改否则 agent 会按旧规范干活反而添乱。5.3 分享与获取怎么找到别人写的好 skill热词里skills 推荐find skillsclaude 国内安装 skills 官方市场前任 skills 官方下载这些反映的是用户对现成 skill的强烈需求。目前获取渠道主要有几个官方市场、社区分享、GitHub 仓库。我的建议是优先用官方市场的其次用知名社区贡献者的最后才考虑来源不明的。skill 本质上是给 agent 的执行指令来源不明的 skill 可能包含不安全的操作比如让你执行某些命令、访问某些地址。用之前一定要读一遍内容确认没有风险。自己写 skill 分享出去也是积累个人影响力的好方式。写得好、用得广的 skill会成为你的技术名片。5.4 常见故障排查从无法加载到触发异常用 skill 的过程中会遇到各种问题我整理几个高频的现象可能原因排查方向skill 完全不加载目录位置不对、文件格式错误检查存放路径是否符合工具约定文件是否为合法 markdown该触发时不触发描述太模糊、触发条件太窄优化元信息描述放宽触发条件不该触发时乱触发描述太宽泛、与其他 skill 重叠收窄描述明确边界加互斥标记加载了但输出不对主体内容逻辑不清、示例缺失补充步骤和正反示例明确输出格式多个 skill 冲突触发条件重叠、优先级不明明确区分职责设置优先级热词里codex is ignoring 1 unrecognized configuration settingcodex 无法加载组织设置cc switch local proxy failed这些属于工具本身的配置问题跟 skill 不直接相关但会间接影响 skill 的使用。遇到这类问题先解决工具配置再排查 skill。6. 我踩过的坑和几条实在建议第一个坑是贪多。我一开始写了一个万能skill想把所有前端规范都塞进去结果 agent 加载后反而不知道该关注什么输出质量下降。后来拆成五个小 skill效果立竿见影。skill 这东西少即是多。第二个坑是描述写得太官方。我早期写描述喜欢用本 skill 用于……这种句式后来发现 agent 对口语化、场景化的描述理解更好。改成当用户要提交代码时用这个 skill 生成规范的 commit message触发准确率明显提升。第三个坑是不测试就上线。有次改了一个 skill 的描述没测就提交了结果团队里所有人的 agent 都开始误触发折腾了半天才回滚。skill 的变更一定要测尤其是影响触发逻辑的变更。几条实在建议skill 文件保持短小超过 500 行的考虑拆分每个 skill 都要有明确的不适用场景定期清理不再使用的 skill避免干扰团队 skill 要有 owner不能没人管分享 skill 前先自己用一周确认稳定再发。最后说一句skills 这个机制还在快速演进不同工具的格式和玩法可能变。但核心思路是稳定的把经验结构化、把知识模块化、让 agent 按需调用。抓住这个核心具体格式怎么变都能跟上。我自己是从每次贴一大段提示词一路踩坑过来的现在回头看skills 带来的效率提升是实打实的值得花时间认真投入。