1. 从“skills”这个词说起它到底在解决什么问题第一次看到“skills”这个标题很多人会以为是某个泛泛的能力清单或者又是一篇讲“如何提升自己”的鸡汤。但如果你最近在折腾 Claude Code、Codex、Cursor 这类 AI 编程工具就会发现“skills”已经变成了一个非常具体的工程概念——它指的是给 AI Agent 挂载的一套可复用、可组合、可版本管理的技能包。你可以把它理解成给一个刚入职的实习生发了一本《岗位操作手册》手册里写清楚了遇到什么场景该调用什么工具、按什么顺序执行、输出什么格式。我最早接触这个概念是在 Claude Code 的插件体系里。当时我一直在想一个问题为什么同一个模型别人用起来像开了挂我用起来就像在跟一个失忆的实习生对话后来才明白差距不在模型本身而在上下文工程和技能编排。skills 就是上下文工程落地的最小单元。它把一个具体的任务流程——比如“读取 Figma 设计稿并生成 React 组件”“分析日志并定位异常堆栈”“对指定目录做安全审计”——封装成一个独立的、带元数据的模块Agent 在需要的时候自动加载不需要的时候完全不占用上下文窗口。这件事的意义在于它把 prompt engineering 从“一次性手写”变成了“工程化复用”。以前你写一个复杂的系统提示词改一个标点都可能影响全局现在你把能力拆成一个个 skills每个 skill 有自己的触发条件、输入输出定义和依赖声明互不干扰。这就像从“写一个几千行的单体脚本”进化到“用微服务架构组织代码”维护成本和扩展性完全不是一个量级。适合谁来参考这篇内容三类人。第一类是已经在用 Claude Code、Codex 或类似 Agent 工具但总觉得“差点意思”的开发者第二类是团队里负责搭建 AI 辅助开发流程的技术负责人第三类是对 Agent 架构感兴趣、想搞清楚“skills 到底怎么落地”的工程师。不管你是刚装好 Claude Code 的新手还是已经在写自定义 plugin 的老手下面这些拆解应该都能让你少走一些弯路。2. skills 的核心设计思路为什么不是简单的 prompt 模板2.1 从“单体提示词”到“技能模块化”的演进逻辑早期用 Claude Code 或者 Codex 的时候大多数人的做法是把所有要求塞进一个系统提示词里你是一个资深前端工程师你要遵循以下代码规范你要先读文件再改代码你要写测试你要……结果就是提示词越写越长模型反而越来越糊涂。原因很简单上下文窗口是有限资源无关信息越多关键指令的注意力权重就越低。这就像你给下属交代任务如果一次性说五十条注意事项他大概率一条都记不住。skills 的设计思路正好反过来。它不追求“一次说全”而是追求“按需加载”。每个 skill 是一个独立目录里面通常包含一个SKILL.md或skill.json作为元数据描述声明这个技能叫什么、什么时候触发、需要哪些工具权限、输出什么格式。Agent 在运行过程中根据当前任务动态匹配 skills只把相关的那个加载进上下文。我实测下来同样一个“重构这个 React 组件”的任务用单体提示词时模型经常漏掉测试步骤改成 skill 编排后测试环节的触发率从大概六成提升到了九成以上。这个演进背后有一个很朴素的工程原则关注点分离。写代码的人都知道一个函数只做一件事一个模块只负责一个领域。skills 就是把这条原则搬到了 Agent 的能力组织上。你有一个专门做代码审查的 skill一个专门做依赖升级的 skill一个专门做文档生成的 skill它们各自独立迭代互不影响。哪天代码规范变了你只改审查那个 skill不用动其他任何东西。2.2 skills、plugin、agents 三者的关系与边界热词里同时出现了 skills、plugin、agents很多人搞不清楚它们的区别。我用一个类比来说明Agent 是员工skills 是员工的技能plugin 是员工可以使用的工具。员工Agent接到任务后判断需要用到哪项技能skill然后拿起对应的工具plugin去执行。具体到 Claude Code 的体系里Agent 是那个主循环负责理解用户意图、规划步骤、调用工具。skills 是挂在 Agent 身上的能力描述告诉它“遇到这类任务时应该按什么流程走”。plugin 则更偏向底层能力扩展比如接入一个外部 API、增加一个文件解析器、连接一个数据库。三者配合起来才能让 Agent 从“能聊天”变成“能干活”。这里有一个容易踩的坑不要把本该做成 plugin 的东西硬塞进 skill。我见过有人写了一个 skill里面用自然语言描述“请调用某个 HTTP 接口获取数据”结果模型每次都要自己拼 URL、处理鉴权稳定性极差。正确做法是把 HTTP 调用封装成 pluginskill 里只写“调用 xxx 工具获取数据”。skill 负责流程编排plugin 负责具体执行边界清晰了整个系统才可靠。2.3 为什么 skills 特别适合前端开发和代码审查场景热词里“前端开发skills”出现频率很高这不是偶然。前端开发有几个特点流程标准化程度高、工具链成熟、输入输出格式相对固定。比如“根据设计稿生成组件”这件事步骤基本是固定的读取设计稿元数据、提取颜色和间距、生成组件骨架、补充样式、写单元测试。这种高度结构化的任务最适合用 skill 来固化。代码审查也是同理。一个合格的审查 skill 应该包含检查命名规范、检查边界条件、检查错误处理、检查性能隐患、输出审查意见格式。这些检查项可以逐条迭代今天发现漏了“未处理空数组”明天就在 skill 里加一条。用单体提示词做这件事改一处经常影响另一处用 skill 做每条规则独立增删改都很干净。我自己的经验是凡是重复出现三次以上的任务流程都值得抽成一个 skill。第一次做的时候手动来第二次做的时候记录步骤第三次做的时候就应该把它固化下来。这个习惯坚持两个月你的 Agent 会变得越来越“懂你”因为它的能力库是你一点一点喂出来的。3. 核心细节解析一个 skill 到底由哪些部分组成3.1 元数据定义触发条件、权限声明与版本管理一个规范的 skill元数据部分至少要包含这几项名称、描述、触发条件、所需权限、版本号。名称要短且唯一描述要一句话说清楚这个 skill 干什么触发条件要写明白什么情况下 Agent 应该加载它。我见过很多人写触发条件时写得太宽泛比如“当用户需要写代码时”结果这个 skill 几乎每次都被加载上下文里塞满了用不上的指令。触发条件应该尽量具体。比如“当用户要求对指定目录进行安全审计且目录中包含 package.json 时”就比“当用户需要安全检查时”好得多。权限声明也很关键一个需要读写文件系统的 skill 和一个只读的 skill风险等级完全不同。Claude Code 在这方面做得比较细它会在加载 skill 时检查权限避免 Agent 越权操作。版本管理是很多人忽略的一点。skills 是会迭代的今天加一条规则明天改一个输出格式。如果没有版本号你很难追踪“为什么上周还好用的流程这周出问题了”。我的做法是每个 skill 目录下放一个CHANGELOG.md每次修改记录改了什么、为什么改。这个习惯在团队协作时尤其重要别人用你的 skill 出问题时你能快速定位是哪次改动引入的。3.2 指令正文如何写出模型能稳定执行的步骤指令正文是 skill 的核心也是最考验写作功力的地方。写得好模型执行得稳写得差模型每次都能给你整出新花样。我总结了几条原则都是踩坑踩出来的。第一条用祈使句不用描述句。写“读取目标文件”而不是“模型应该读取目标文件”。写“如果文件不存在输出错误信息并终止”而不是“当文件不存在时可能需要处理一下”。模型对祈使句的遵循度明显更高。第二条步骤要编号但不要超过七步。人的短期记忆容量是七加减二模型虽然理论上能处理更多但步骤太多时注意力会分散。如果一个流程超过七步考虑拆成两个 skill用第一个 skill 的输出作为第二个的输入。第三条每个步骤都要有明确的输入和输出。比如“读取 package.json提取 dependencies 字段输出为 JSON 格式”。这样模型知道这一步做完之后手里应该有什么下一步才能接得上。我见过一个 skill 写“分析依赖关系”结果模型分析完输出了一段自然语言描述下一步根本没法用。第四条异常处理要写清楚。正常流程谁都会写关键是出错时怎么办。文件读不到怎么办网络超时怎么办输出格式不符合预期怎么办这些都要在 skill 里明确。我的习惯是每个 skill 末尾加一段“错误处理”列出可能出现的异常和对应的处理方式。3.3 工具依赖与上下文注入让 skill 真正跑起来skill 本身只是描述真正执行还需要工具支持。一个 skill 可能依赖文件读写、命令执行、网络请求、数据库查询等能力。这些能力在 Claude Code 里通过 plugin 提供在 Codex 里通过工具注册机制提供。写 skill 的时候要明确声明依赖哪些工具否则 Agent 加载了 skill 却发现没有对应工具任务就会卡住。上下文注入是另一个关键点。skill 在执行过程中可能需要读取项目配置、环境变量、历史记录等信息。这些信息不应该硬编码在 skill 里而应该通过上下文注入的方式动态提供。比如一个“部署”skill它需要知道目标环境是测试还是生产这个信息应该从当前会话的上下文里取而不是写死在 skill 描述里。我自己的做法是在 skill 元数据里声明“需要上下文项目根目录、当前分支、环境变量 DEPLOY_ENV”Agent 加载 skill 时会自动把这些信息注入进去。这样同一个 skill 可以在不同项目、不同环境下复用不用改一行描述。这个设计思路和函数传参是一样的skill 是函数体上下文是参数工具是运行时环境。4. 实操过程从零搭建一个可用的 skill4.1 环境准备Claude Code 与 Codex 的安装配置要点先说 Claude Code 的安装。官方推荐的方式是通过 npm 全局安装命令是npm install -g anthropic-ai/claude-code。装完之后在项目目录下运行claude就能启动。这里有一个坑Node 版本不能太低建议 18 以上否则某些依赖会报错。我在一台老机器上用过 Node 16结果安装过程各种警告虽然最后能跑但稳定性明显不如新版本。Windows 用户要注意Claude Code 在 Windows 上的支持是后来才完善的。早期版本在 Windows 上经常出现路径分隔符问题skill 里写的相对路径在 Windows 上解析不对。解决办法是在 skill 里统一用正斜杠或者在元数据里声明平台兼容性。现在新版本已经好很多了但如果你用的是比较老的版本建议升级。Codex 的安装相对简单官网下载安装包或者通过包管理器安装都可以。Codex 的配置文件和 Claude Code 不通用skill 的目录结构也有差异。如果你两个都在用建议把 skill 写成平台无关的格式然后用一个转换脚本分别生成两个平台能识别的版本。我写过一个简单的 Node 脚本做这件事核心逻辑就是读同一个源文件按平台输出不同的元数据格式。VS Code 用户可以直接装 Claude Code 的 VS Code 扩展装完之后在编辑器里就能调用。这个扩展的好处是它能自动把当前打开的文件、光标位置、选中内容作为上下文传给 Agent写 skill 的时候可以利用这些信息。比如一个“解释选中代码”的 skill在 VS Code 里就能直接拿到选中的文本不用再让用户手动指定。4.2 第一个 skill从需求到落地的完整流程我拿一个真实需求来演示自动为指定 React 组件生成单元测试。这个需求在前端开发里很常见流程也相对固定适合做第一个 skill。第一步明确触发条件。这个 skill 应该在用户说“给这个组件写测试”或者“生成测试文件”时触发。触发条件写成“当用户要求为 React 组件生成单元测试且目标文件扩展名为 .tsx 或 .jsx 时”。第二步拆解步骤。我把它拆成五步读取目标组件文件、分析组件的 props 和状态、确定需要测试的分支、生成测试代码、写入测试文件。每一步都要写清楚输入输出。比如第一步“读取目标组件文件输出文件内容字符串”第二步“分析文件内容提取组件名称、props 类型、条件渲染分支输出为结构化 JSON”。第三步声明工具依赖。这个 skill 需要文件读取工具、文件写入工具可能还需要一个 AST 解析工具来提取组件信息。如果平台没有现成的 AST 工具可以用正则做简单提取但稳定性会差一些。我的建议是尽量用平台提供的结构化工具不要自己写正则硬解析。第四步写错误处理。文件不存在怎么办组件里没有 props 怎么办测试文件已存在怎么办这些都要覆盖。我的处理方式是文件不存在就报错终止没有 props 就生成基础渲染测试测试文件已存在就询问用户是否覆盖。第五步测试和迭代。写完 skill 之后找三到五个不同的组件跑一遍看输出是否稳定。我第一版写完之后发现模型经常漏掉异步状态的测试后来在步骤里加了一条“如果组件包含 useEffect 或异步数据获取必须生成对应的异步测试用例”问题就解决了。4.3 调试与验证怎么判断一个 skill 写得好不好判断 skill 质量有几个硬指标。第一是触发准确率该触发的时候触发不该触发的时候不触发。我见过一个 skill 因为触发条件写得太宽泛几乎每次对话都被加载结果上下文里全是无关指令模型反而变笨了。测试方法是准备十个不相关的任务看这个 skill 会不会被误触发。第二是执行稳定性同一个任务跑十次输出格式是否一致。如果十次里有三次格式不对说明指令写得不够明确。解决办法是把输出格式用示例写出来模型对示例的遵循度远高于对描述的理解。第三是错误处理覆盖率故意制造一些异常情况看 skill 是否能正确处理。比如把目标文件删掉、把权限改成只读、传入一个空目录看 Agent 是报错终止还是胡编乱造。好的 skill 应该在这些情况下给出清晰的错误信息而不是硬着头皮往下走。第四是上下文占用一个 skill 加载后占用了多少 token。如果超过两千 token就要考虑是不是写得太啰嗦了。我的经验是一个功能单一的 skill 应该控制在一千 token 以内复杂的流程拆成多个 skill 组合使用。5. 常见问题与排查技巧实录5.1 安装与配置阶段的典型报错Claude Code 安装过程中最常见的问题是网络相关的报错。因为 npm 源的问题国内用户经常遇到下载超时。解决办法是换一个稳定的镜像源或者用离线安装包。我一般会建议先把 npm 源配置好再执行安装命令能省掉很多麻烦。另一个高频问题是权限报错。在 Linux 或 macOS 上全局安装可能需要 sudo但用 sudo 装完之后又会出现权限归属问题。我的做法是用 nvm 管理 Node 版本在用户目录下安装完全避开权限问题。Windows 用户如果遇到路径相关报错检查一下环境变量里有没有多余的空格或者中文路径这两个是重灾区。Codex 的安装问题主要集中在依赖缺失上。有些系统缺少必要的运行库安装程序会静默失败。解决办法是看安装日志找到缺失的依赖手动补上。另外 Codex 的配置文件路径在不同系统上不一样写 skill 的时候如果涉及路径一定要用平台无关的写法。5.2 skill 不触发或触发错误的排查思路skill 不触发先检查三件事触发条件是否写得太窄、元数据格式是否正确、skill 目录是否在 Agent 的搜索路径下。我遇到过最常见的情况是元数据里少了一个逗号导致整个文件解析失败Agent 根本看不到这个 skill。排查方法是让 Agent 列出当前加载的所有 skills看目标 skill 在不在列表里。触发错误则是另一个极端。如果 skill 在不该触发的时候触发了先看触发条件里有没有过于宽泛的关键词。比如写了“当用户提到测试时”那用户说“这个功能测试过了”也会触发。解决办法是把触发条件写得更具体加上“当用户要求生成测试文件时”这样的限定。还有一种情况是多个 skill 同时触发互相干扰。比如一个“代码审查”skill 和一个“代码重构”skill如果触发条件有重叠Agent 可能会同时加载两个然后不知道该听谁的。解决办法是在元数据里加优先级或者在触发条件里做互斥声明。5.3 执行结果不稳定的调优方法执行结果不稳定九成以上的原因是指令不够明确。模型不是人它不会“领会精神”你写什么它就执行什么。如果输出格式每次都不一样就在 skill 里加一个输出示例把期望的格式完整写出来。如果步骤顺序经常乱就把步骤编号写清楚并且加上“必须按顺序执行”的强调。温度参数也会影响稳定性。Claude Code 和 Codex 都允许调整生成温度温度越高输出越多样但稳定性越差。对于需要严格按流程执行的 skill建议把温度调低。我一般会在 skill 元数据里声明推荐温度Agent 加载时自动应用。还有一个容易被忽略的点是上下文污染。如果同一个会话里之前执行过其他任务残留的上下文可能会影响当前 skill 的执行。解决办法是在 skill 开头加一句“忽略之前的对话历史只根据当前任务执行”。这句话看起来简单但实测能显著提升稳定性。5.4 常见问题速查表问题现象可能原因排查方法解决方式skill 完全不触发元数据格式错误让 Agent 列出已加载 skills检查 JSON 语法确保文件在搜索路径下skill 频繁误触发触发条件太宽泛查看触发关键词增加限定条件提高触发门槛执行步骤顺序混乱指令未强调顺序检查步骤描述加编号并注明“必须按顺序执行”输出格式不一致缺少输出示例对比多次输出在 skill 里加入完整输出示例执行中途卡住工具依赖缺失查看执行日志声明所需工具确保平台已注册结果受历史对话影响上下文污染清空会话后重试skill 开头加“忽略历史”指令权限报错未声明所需权限查看权限声明在元数据里补充权限声明跨平台路径错误路径写法不兼容在目标平台测试统一用正斜杠声明平台兼容性6. 进阶玩法让 skills 组合出更强的能力6.1 skill 链式调用与条件分支设计单个 skill 的能力是有限的真正强大的是 skill 之间的组合。我常用的模式是链式调用第一个 skill 负责分析输出结构化结果第二个 skill 接收这个结果执行具体操作第三个 skill 做验证和收尾。比如“分析组件 - 生成测试 - 运行测试 - 输出报告”就是一条典型的链。链式调用的关键是接口约定。第一个 skill 的输出格式必须和第二个 skill 的输入格式严格匹配。我的做法是在每个 skill 的元数据里声明输入输出 schemaAgent 在串联时会自动校验。如果格式不匹配Agent 会报错而不是硬着头皮往下传。条件分支是另一个实用模式。比如一个“代码修改”skill可以根据文件类型走不同的分支如果是 TypeScript 文件走类型检查分支如果是样式文件走样式校验分支。实现方式是在 skill 里写清楚判断条件Agent 会根据当前上下文自动选择分支。这个模式比写多个独立 skill 更紧凑但要注意分支不要太多超过三个分支就建议拆开。6.2 团队协作中的 skill 版本管理与共享团队里用 skills最大的挑战是版本同步。张三改了一个 skill李四那边还是旧版本执行结果不一致排查起来很头疼。我的做法是把 skills 放在一个独立的 Git 仓库里每个 skill 一个目录用 Git 做版本管理。团队约定好修改 skill 必须提 PR经过 review 才能合并。共享方面可以搭建一个内部的 skill 市场把常用的 skill 发布上去团队成员按需安装。Claude Code 官方也有 skill 市场但国内访问不太稳定建议团队内部自建一个。实现方式很简单就是一个静态文件服务器放一个索引文件列出所有可用 skill 及其下载地址。版本兼容性也要考虑。如果某个 skill 依赖特定版本的 Claude Code 或 Codex要在元数据里声明最低版本要求。Agent 加载时会检查版本不满足就提示用户升级。这个机制能避免很多“为什么在我机器上跑不通”的问题。6.3 从 skills 到 agents能力编排的下一步skills 解决的是“单个能力怎么复用”agents 解决的是“多个能力怎么协同”。当你的 skill 库积累到一定规模就可以考虑定义专门的 agent 了。比如一个“前端开发 agent”它挂载了组件生成、测试生成、样式检查、依赖升级等一组 skills用户只需要说“帮我开发这个功能”agent 会自动编排这些 skills 完成任务。定义 agent 的核心是能力边界和协作规则。哪些 skill 归这个 agent 管skill 之间的调用顺序是什么出现冲突时怎么裁决这些都要提前设计好。我的经验是一个 agent 挂载的 skills 不要超过十个太多了会互相干扰。如果确实需要更多能力拆成多个 agent用主 agent 做调度。这个方向目前还在快速演进中Claude Code 和 Codex 都在不断更新 agent 相关的功能。我的建议是先把单个 skill 写好、用稳再考虑往上叠 agent。地基不牢楼越高越危险。我见过有人一上来就搞复杂的 agent 编排结果单个 skill 都没写明白整个系统跑起来全是问题。7. 我踩过的坑和几条实在建议第一个坑是贪多。刚开始写 skill 的时候我总想一个 skill 把所有情况都覆盖了结果写出来两千多 token模型执行时经常顾此失彼。后来学乖了一个 skill 只做一件事做精做透。现在我的 skill 库里最长的也就八百 token但每个都很稳。第二个坑是不写错误处理。正常流程跑通很容易异常情况才是考验。我有一次写了一个文件处理 skill没考虑文件不存在的情况结果 Agent 在文件缺失时自己编了一个文件内容继续往下跑输出了一堆看似合理实则完全错误的结果。从那以后每个 skill 我都强制自己写错误处理分支。第三个坑是忽略上下文长度。skills 加载进上下文是要占 token 的如果同时加载太多 skill留给实际任务的上下文就不够了。我的做法是按需加载并且定期清理不再使用的 skill。Claude Code 有上下文使用情况的统计我一般会盯着这个指标超过七成就要考虑精简了。最后一个建议是从小处着手快速迭代。不要想着一次写出完美的 skill先写一个能用的版本跑起来发现问题再改。我现在的习惯是每周花半小时回顾这周用到的 skill哪个不好用就改一改。积少成多半年下来你的 skill 库就会变成一笔真正的资产。这个东西没有捷径就是不断用、不断改、不断沉淀。