1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你随便翻翻热搜词就能看到一堆相关组合claude code skills、codex skills、agent skills测试、skills开发、skills推荐、find skills、superpower skills……看起来像是某种插件又像是某种能力包还有人把它跟agents、plugin放在一起讨论。那它到底是什么我自己的理解是skills 本质上是一套“可复用的能力描述单元”它把某个具体任务的操作流程、工具调用方式、上下文约束、输出格式打包成一个结构化的模块让 AI 编程助手比如 Claude Code、Codex 这类工具在遇到对应场景时能够直接调用这套预设好的“技能”而不是每次从零开始推理。你可以把它类比成给一个新员工写的 SOP 手册——不是告诉他“你要聪明一点”而是告诉他“遇到 A 情况先做 B再检查 C最后输出 D 格式”。这个思路解决的核心痛点是大模型在通用对话里很聪明但在具体工程任务里经常“飘”。你让它改一个 React 组件的样式它可能给你重写整个文件你让它跑一个数据库迁移它可能忘了先备份。skills 的出现就是把那些“老手才知道的隐性规则”显性化、模块化让 AI 在执行时有一个明确的轨道可以走。适合谁来关注这个内容三类人最应该花时间研究第一类是日常用 Claude Code 或 Codex 写代码的开发者你不需要自己从零开发 skills但你需要知道怎么找到好用的、怎么安装、怎么组合第二类是团队里的技术负责人你想把团队内部的代码规范、部署流程、审查清单固化成 AI 能理解的形式skills 就是最自然的载体第三类是对 agent 架构感兴趣的产品或工具开发者skills 的设计思路本身就是一种轻量级的 agent 能力编排方案理解它对设计自己的系统很有帮助。接下来的内容我会从整体设计思路、核心细节、实操过程、常见问题四个维度展开尽量把我知道的、踩过的、验证过的都倒出来。不会只讲概念每个环节都会给到可操作的步骤和参数说明。2. 内容整体设计与思路拆解2.1 为什么是“技能包”而不是“提示词模板”很多人第一次听到 skills 会想这不就是高级一点的 prompt template 吗我直接写一段系统提示词不就行了我一开始也这么觉得但实际用下来发现差别很大。提示词模板是扁平的、静态的你写一段话模型读一遍然后开始干活。它的问题在于当任务变复杂时提示词会膨胀到几千字模型注意力被稀释关键约束反而被忽略。而且提示词很难版本管理改一处可能影响另一处。skills 的设计是结构化的、可组合的。一个 skill 通常包含几个明确的部分触发条件什么时候用这个技能、前置依赖需要哪些工具或环境、执行步骤分步骤的操作序列、输出规范结果应该长什么样、边界条件什么情况下不应该用。这种结构让模型在调用时能快速定位到关键信息而不是在一大段文字里大海捞针。更重要的是skills 可以嵌套和组合。比如你有一个“创建 React 组件”的 skill里面可以引用“运行测试”的 skill 和“格式化代码”的 skill。这种组合能力让复杂工作流可以被拆解成可维护的单元而不是一个巨大的单体提示词。2.2 当前主流工具对 skills 的支持形态从热搜词来看讨论最多的两个载体是Claude Code和Codex。这两个工具对 skills 的支持方式不太一样我分别说一下我观察到的情况。Claude Code 这边skills 通常以文件形式存在放在项目的特定目录下比如.claude/skills/或者用户级配置目录。每个 skill 是一个独立的文件或文件夹里面包含描述文件和执行逻辑。Claude Code 在运行时会根据当前任务上下文自动判断是否需要加载某个 skill。你也可以手动触发比如在对话里明确说“使用 XX skill 来处理这个任务”。Codex 这边skills 的概念更偏向于“插件式能力扩展”。从热搜词里能看到codex skills、codex接入deepseek、codex安装教程这些组合说明很多人在尝试把 Codex 跟不同的模型后端和技能包对接。Codex 的 skills 通常需要通过配置文件注册然后以命令或 API 的形式调用。还有一个值得注意的趋势是agents 和 skills 的融合。热搜词里有langchain deep agents、agents anywhere、agent skills测试说明社区正在探索把 skills 作为 agent 的能力单元来编排。这种思路下一个 agent 不再是一个巨大的单体而是由多个 skills 组装而成的复合体每个 skill 负责一个具体能力域。2.3 设计一个 skill 时最该想清楚的三个问题我自己的经验是写一个能用的 skill 不难但写一个好用的 skill 需要提前想清楚三件事。第一触发边界在哪里。这个 skill 应该在什么情况下被调用是用户明确要求时还是模型自动判断如果自动判断判断依据是什么我见过很多 skill 失败的原因不是逻辑不对而是触发条件太模糊导致该用的时候没用不该用的时候乱用。一个实用的技巧是在 skill 描述里写清楚“不适用场景”这比只写“适用场景”更能帮助模型做判断。第二执行步骤的粒度怎么定。太粗了模型自由发挥空间太大太细了又变成死板脚本。我的经验是关键决策点要细机械操作可以粗。比如“先检查当前分支是否有未提交的更改”这种关键安全检查要写成明确步骤“运行测试命令”这种标准操作可以只给命令模板让模型根据项目实际情况填充参数。第三输出格式怎么约束。如果你希望 skill 的输出能被后续流程消费那输出格式必须严格定义。我一般会在 skill 里明确指定输出是 JSON 还是 Markdown包含哪些字段字段类型是什么有没有可选字段。这一步偷懒的话后面组合多个 skill 时会出现各种解析错误。3. 核心细节解析与实操要点3.1 skill 文件的基本结构长什么样虽然不同工具的具体格式有差异但一个典型的 skill 文件通常包含以下几个部分。我以一个“代码审查”场景为例来说明。name: code-review description: 对指定文件或目录进行代码审查检查常见问题并输出结构化报告 trigger: - 用户明确要求审查代码 - 提交 PR 前自动触发 dependencies: - 需要访问项目根目录 - 需要读取 git diff 的能力 steps: - 获取待审查的文件列表 - 逐个文件检查命名规范、错误处理、边界条件 - 汇总问题并按严重程度排序 output: format: markdown sections: - 严重问题 - 建议改进 - 通过项这个结构里trigger决定了什么时候加载dependencies决定了运行前提steps是执行逻辑output是结果规范。实际写的时候steps 部分可以更详细甚至包含条件分支和循环逻辑。注意不同工具对 skill 文件的字段命名和格式要求不同写之前一定要先看对应工具的官方文档或社区示例不要凭感觉写。3.2 触发条件的写法技巧触发条件是 skill 能否被正确调用的关键。我踩过的坑是一开始只写“当用户要求做 X 时触发”结果模型经常在该触发的时候不触发因为用户可能用不同的措辞表达同一个需求。后来我改进的方法是同时写正向触发词和负向排除词。正向触发词列出用户可能用的各种表达方式负向排除词列出容易混淆但不应触发的情况。比如一个“数据库迁移”的 skill正向触发迁移数据库、执行 migration、更新 schema、改表结构负向排除查询数据库、备份数据库、优化查询这样模型在判断时就有更清晰的边界。另外如果工具支持可以给触发条件加权重让某些关键词的优先级更高。3.3 步骤设计中的安全检查点这是我最想强调的部分。skills 让 AI 自动执行任务但自动执行意味着一旦出错后果可能比手动操作更严重。所以每个 skill 里都应该有安全检查点。我一般会在三个位置加检查执行前检查环境状态比如当前分支、未提交更改、依赖版本、执行中检查中间结果比如生成的代码是否能通过语法检查、执行后检查最终状态比如测试是否通过、文件是否被正确修改。这些检查点不需要很复杂有时候就是一行命令的事但能避免很多灾难性错误。我见过有人写了一个自动重构的 skill没有加“先提交当前更改”的检查结果重构失败后代码回滚不了损失了半天的工作。3.4 输出格式的约束方法如果你希望 skill 的输出能被其他工具或流程消费输出格式必须严格定义。我常用的做法是在 skill 里直接给出输出模板并说明每个字段的含义和取值范。比如一个“生成 API 文档”的 skill输出模板可能是{ endpoint: /api/v1/users, method: GET, parameters: [ {name: page, type: integer, required: false, default: 1} ], response: { code: 200, body: {} } }然后在 skill 描述里说明parameters数组中的每个对象必须包含name、type、required三个字段default可选。这样模型在生成时就有明确的约束不会随意发挥。提示如果输出格式比较复杂可以在 skill 里附一个示例输出模型照着示例生成比照着文字描述生成要准确得多。4. 实操过程与核心环节实现4.1 环境准备安装和配置基础工具在开始使用 skills 之前你需要先有一个支持 skills 的 AI 编程工具。从热搜词来看Claude Code 和 Codex 是讨论最多的两个。我分别说一下安装和配置的基本流程。Claude Code 的安装根据社区里的讨论通常有几种方式通过 npm 全局安装、通过官方安装脚本、或者在某些 IDE 的插件市场里安装。安装完成后你需要配置 API 访问凭证。如果你在国内网络环境下使用可能需要配置代理或者使用兼容的 API 端点。热搜词里有claude code 调用lmstudio的本地模型说明很多人也在尝试用本地模型来驱动 Claude Code这种方式的好处是不依赖外部服务但需要本地有足够的计算资源。Codex 的安装热搜词里有codex安装教程、codex安装包、codex下载、codex官网下载说明安装过程对很多人来说是个门槛。Codex 通常需要先安装 Node.js 环境然后通过包管理器安装。安装完成后需要登录账号或配置 API key。热搜词里还有codex接入deepseek说明 Codex 支持切换不同的模型后端这对想控制成本的开发者来说是个有用的特性。注意安装过程中如果遇到网络问题优先检查你的包管理器配置和网络环境。不要盲目复制网上的命令先确认命令来源可靠。4.2 获取和安装 skills 的几种途径skills 从哪里来我总结了几种常见途径。第一种是官方或社区市场。热搜词里有claude 国内安装skills 官方市场、find skills、skills推荐说明已经有一些集中的 skills 分发渠道。这些市场里的 skills 通常经过一定筛选质量相对有保障。安装方式一般是复制文件到指定目录或者通过命令行工具一键安装。第二种是团队内部自建。这是我认为最有价值的方式。每个团队都有自己的代码规范、部署流程、审查清单把这些固化成 skills新成员入职时直接安装一套就能让 AI 助手按照团队标准来工作。热搜词里的skills开发、idea使用skills、vscode配置claude code都指向这个方向。第三种是自己从零写。如果你有非常特定的工作流市场上找不到现成的那就自己写。写 skill 的过程本身也是梳理工作流的过程很多时候写着写着就发现原来的流程里有冗余步骤。4.3 一个完整 skill 的编写和调试过程我拿一个实际例子来演示写一个“自动生成单元测试”的 skill。第一步明确目标和边界。这个 skill 的目标是给定一个源文件自动生成对应的单元测试文件。边界是只处理 JavaScript/TypeScript 文件只生成基础测试用例不处理复杂的 mock 场景。第二步写触发条件。正向触发生成测试、写单测、补充测试用例。负向排除运行测试、修复测试、测试覆盖率报告。第三步写执行步骤。我一般会写成编号列表读取目标源文件识别导出的函数和类对每个导出项生成至少一个正常路径测试和一个边界条件测试检查项目中是否已有测试框架配置如果没有则使用默认的 Jest 配置将生成的测试写入对应目录文件名遵循[源文件名].test.[扩展名]格式运行生成的测试如果失败则输出失败信息并建议修复方向第四步定义输出格式。输出应该包含生成的测试文件路径、测试用例数量、运行结果摘要。第五步调试。写完 skill 后不要直接用在重要项目上。先找一个简单的测试项目手动触发这个 skill观察它的执行过程。重点看触发是否准确、步骤是否按预期执行、输出是否符合格式要求。如果发现问题回到 skill 文件修改对应部分再次测试。这个循环可能要重复好几次才能稳定。4.4 把 skills 组合成工作流单个 skill 解决单个问题但实际工作中往往需要多个 skill 串联。比如一个完整的“功能开发”工作流可能包含需求分析 skill → 代码生成 skill → 测试生成 skill → 代码审查 skill → 提交信息生成 skill。组合的方式有两种。一种是显式串联你在对话里依次调用每个 skill前一个的输出作为后一个的输入。这种方式可控性强但需要手动操作。另一种是隐式编排你定义一个更高层的 skill在里面引用其他 skill模型会自动按顺序调用。这种方式效率高但对 skill 之间的接口定义要求更严格。我自己的经验是关键流程用显式串联重复性高的流程用隐式编排。比如发布上线这种高风险操作我宁愿手动一步步确认而日常的代码格式化、测试生成这种低风险操作就可以让模型自动编排。5. 常见问题与排查技巧实录5.1 skill 不触发或错误触发怎么办这是最常见的问题。表现是你期望某个 skill 被调用但模型没有调用或者你不想用某个 skill但模型偏偏调用了。排查思路我一般按这个顺序来先看触发词是否覆盖了你的表达方式。如果你说“帮我检查一下这段代码”但 skill 的触发词里只写了“代码审查”那模型可能匹配不上。解决办法是在触发词里补充同义词和常见表达。再看是否有其他 skill 的触发条件更匹配。如果两个 skill 的触发条件有重叠模型可能会选错。这时候需要调整触发条件的优先级或者在 skill 描述里明确说明“当 X 和 Y 同时出现时优先使用本 skill”。最后看模型是否理解了 skill 的用途。有时候触发词没问题但 skill 的描述写得太抽象模型不确定该不该用。解决办法是把描述写得更具体最好包含一个使用示例。5.2 执行过程中断或报错的排查方法skill 执行到一半失败可能的原因有很多。我整理了一个速查表现象可能原因排查方法执行到某一步卡住该步骤依赖的工具未安装或未配置检查依赖列表手动运行该步骤的命令报权限错误当前用户没有执行该操作的权限检查文件权限、API 权限、目录访问权限输出格式不符合预期输出约束写得太模糊在 skill 里补充输出示例和字段说明执行结果与预期不符步骤逻辑有误或缺少条件判断逐步手动执行 skill 的步骤定位偏差点多个 skill 冲突触发条件重叠或输出格式不兼容调整触发优先级统一输出格式提示如果 skill 涉及文件修改建议在执行前自动创建备份或要求用户确认。我见过太多因为 skill 执行失败导致代码丢失的案例。5.3 性能优化让 skills 跑得更快更稳skills 执行慢通常有两个原因步骤太多或者每步等待时间太长。优化方向也对应两个。减少不必要的步骤。有些 skill 里包含了大量检查步骤虽然安全但拖慢速度。我的做法是把检查分为“必须”和“可选”两类必须的每次都执行可选的根据上下文决定是否执行。并行化独立步骤。如果 skill 里有多个互不依赖的步骤可以让它们并行执行。比如同时检查多个文件的格式而不是一个一个来。不过要注意并行执行对工具的并发能力有要求不是所有环境都支持。缓存重复计算结果。如果某个 skill 经常被调用且每次都要读取相同的配置或依赖信息可以考虑把这些信息缓存起来避免重复读取。5.4 安全使用 skills 的几条底线最后说几条我给自己定的规矩也推荐给你。第一涉及删除、覆盖、推送的操作必须加确认步骤。不要让 skill 自动执行rm -rf、git push --force、drop table这类命令除非你百分之百确定后果可控。第二不要在 skill 里硬编码敏感信息。API key、密码、token 这些东西应该通过环境变量或配置文件注入而不是写在 skill 文件里。热搜词里有agentpoison: red-teaming llm agents via poisoning memory or knowledge ba虽然具体内容我不展开但它提醒我们skill 作为 agent 的知识来源如果被污染或篡改后果可能很严重。所以 skill 文件的来源要可信修改要留痕。第三定期审查已安装的 skills。尤其是从外部获取的 skill要定期检查它是否还在按预期工作有没有被意外修改。我一般每个月会花十分钟过一遍自己常用的 skills确认没有异常。第四新 skill 先在隔离环境测试。不要一上来就在生产项目里用新 skill。找一个测试项目或者用容器/虚拟机隔离环境跑通了再迁移到正式环境。6. 我对 skills 生态的一些个人观察写到这里我想聊几句自己的感受。skills 这个概念之所以在最近半年爆发本质上是因为大家发现大模型的能力上限很高但下限不稳定。你让它做一件它擅长的事它能做得很好但你让它做一件它不熟悉的事它可能犯很低级的错误。skills 就是在拉高下限让模型在特定场景下的表现更可预测。从热搜词里能看到社区正在往几个方向探索。一个是降低使用门槛比如claude code安装、codex安装教程、codex安装包这些词的高频出现说明大量新用户正在涌入他们需要更简单的上手路径。另一个是扩展应用场景比如安卓脱壳skills、idea使用skills、前端开发skills说明 skills 正在从通用编程向垂直领域渗透。还有一个是多工具协同比如cc switch local proxy failed while handling codex endpoint /responses这种报错信息说明很多人在尝试把不同工具串联起来用过程中遇到了兼容性问题。我自己的判断是skills 不会取代提示词工程而是会成为提示词工程的一个更高层抽象。就像函数不会取代变量但函数让代码组织更清晰。未来可能会出现 skills 的包管理生态有版本管理、依赖解析、质量评分就像 npm 之于 JavaScript。到那时候写 skill 可能会成为一种独立的技能甚至是一个职业方向。不过在那之前我建议你先从一个小场景开始写一个自己每天都会用的 skill跑通整个流程。不要一上来就追求大而全先解决一个具体问题拿到正反馈再逐步扩展。我最早写的一个 skill 只是帮我自动生成 git commit message很简单但每天省我两分钟一年下来就是十几个小时。这种小胜利积累多了你对 skills 的理解自然会深入。最后分享一个我最近在用的技巧给每个 skill 写一个“变更日志”。每次修改 skill 后在文件末尾加一行注释记录修改日期、修改原因、修改内容。这样过几个月回头看你能清楚地知道这个 skill 是怎么演变成现在这样的排查问题时也有线索可循。这个习惯看起来不起眼但在我维护了二十多个 skill 之后它帮我省了很多回忆和猜测的时间。