1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是各种开发者群里“skills”这个词出现的频率高得离谱。你随便翻翻热搜词就能看到一堆相关组合Claude Code、Codex、agents、plugin、agent skills测试、codex skills、claude agent skills……这些词全都指向同一个趋势——AI 编程助手正在从“单次对话工具”进化为“可插拔能力平台”。我最早接触这个概念是在折腾 Claude Code 的时候。当时我的理解很简单不就是给 AI 加个提示词模板吗后来踩了几次坑才明白skills 的本质远不止于此。它更像是一套标准化的能力封装协议——把某个特定领域的知识、操作流程、工具调用方式打包成一个可复用的模块让 AI agent 在需要的时候自动加载并执行。打个比方传统的 AI 对话就像你每次找同事帮忙都要从头解释一遍背景而 skills 相当于你给同事准备了一本操作手册他遇到对应场景直接翻到那一页照着做就行。这个差别在简单任务上不明显但一旦涉及多步骤、跨工具、需要特定领域知识的场景效率差距就是数量级的。这篇文章我打算把 skills 这个概念从里到外拆一遍。不管你是刚听说 Claude Code 想试试水还是已经在用 Codex 但总觉得“差点意思”或者你是个想给自己团队搭建 agent 能力体系的技术负责人下面这些内容应该都能帮你少走一些弯路。我会从设计思路讲到具体实操从工具选型讲到踩坑记录尽量把我知道的都倒出来。2. skills 的核心设计思路与方案选型2.1 为什么需要 skills从“万能助手”到“专业分工”先说一个我观察到的现象。很多人第一次用 Claude Code 或者 Codex 的时候会习惯性地把它当成一个“什么都能问”的聊天机器人。你问它写个 Python 脚本它给你写你问它解释一段代码它给你解释。这没问题但你会发现两个瓶颈第一上下文窗口是有限的。你不可能把整个项目的所有规范、所有工具的使用方法、所有历史决策都塞进一次对话里。塞得越多AI 的注意力越分散输出质量反而下降。第二重复劳动太多。比如你们团队有一套固定的代码审查流程每次让 AI 审查代码你都要把规则重新说一遍。这就像你每次让新同事干活都要重新培训一遍累不累skills 要解决的就是这两个问题。它的核心思路是把“能力”从“对话”中解耦出来。你不再需要在每次对话里重复描述某个任务的执行方式而是把它写成一个 skill 文件放在那里。当 AI 判断当前任务需要这个能力时它会自动加载对应的 skill按照里面定义的流程去执行。这个设计思路其实借鉴了软件工程里“模块化”的思想。你写代码不会把所有逻辑塞进一个 main 函数里而是拆成一个个函数、类、模块。skills 就是 AI agent 的“函数库”。2.2 主流方案对比Claude Code skills vs Codex skills vs 通用 plugin目前市面上跟 skills 相关的方案主要有这么几类我列个表对比一下方案类型代表产品核心机制适用场景上手难度官方 skills 体系Claude Code通过 SKILL.md 定义能力agent 自动发现加载代码开发、文件操作、流程自动化中等官方 skills 体系Codex类似机制侧重代码生成与补全代码编写、重构、调试中等通用 plugin 架构各类 IDE 插件通过插件市场安装提供特定功能编辑器增强、语言支持低自建 agent 框架LangChain Deep Agents 等完全自定义灵活度最高复杂业务流程、企业定制高我个人的建议是如果你刚开始接触先从 Claude Code 或者 Codex 的官方 skills 体系入手。原因很简单——官方体系有现成的生态和文档你不需要从零造轮子。等你把官方 skills 的机制摸透了再考虑要不要自建。这里要特别提一下“superpower skills”这个概念。我在一些社区讨论里看到有人用这个词来形容那些能力特别强、覆盖面特别广的 skill 组合。比如一个 skill 负责代码审查一个负责测试生成一个负责文档撰写三个组合起来就是一个完整的开发工作流。这种组合思路很值得借鉴后面我会详细讲怎么设计。2.3 选型时容易忽略的三个关键点在决定用哪套 skills 方案之前有三个点我建议你先想清楚第一你的 agent 运行在什么环境里是在本地 IDE 里比如 VS Code 配置 Claude Code还是在云端本地环境的好处是文件访问方便坏处是配置麻烦云端环境反过来。这个选择会直接影响你能用哪些 skill。第二你的 skill 需要调用外部工具吗有些 skill 只是纯文本的流程指导有些则需要调用 API、执行命令、读写数据库。后者对运行环境的要求高得多。我见过有人写了个 skill 想调用本地模型比如 Claude Code 调用 LMStudio 的本地模型结果发现网络配置和权限管理比想象中复杂。第三你打算自己写 skill 还是用现成的官方市场里已经有不少好用的 skill但如果你有特殊需求自己写是绕不开的。自己写的好处是完全可控坏处是要花时间调试。我的经验是先用现成的跑通流程再针对痛点自己写。3. 核心细节解析与实操要点3.1 skill 文件的结构一个 skill 到底长什么样很多人以为 skill 就是一个提示词文件其实不是。一个完整的 skill 通常包含这几个部分元信息skill 的名称、描述、触发条件。这部分决定了 agent 什么时候会加载这个 skill。能力定义这个 skill 能做什么不能做什么。边界要清晰否则 agent 会乱用。执行流程具体的步骤说明。这是 skill 的核心要写得足够详细让 agent 能照着执行。工具依赖这个 skill 需要调用哪些外部工具或 API。示例给 agent 看的输入输出示例帮助它理解预期行为。我刚开始写 skill 的时候犯过一个错误把执行流程写得太笼统。比如我写“检查代码质量”但没说什么叫“检查”、检查哪些维度、发现问题后怎么处理。结果 agent 执行的时候完全靠猜输出质量很不稳定。后来我把流程拆成“检查命名规范 → 检查错误处理 → 检查边界条件 → 生成报告”四步每一步都有明确的判断标准效果立刻好了很多。提示写 skill 的执行流程时假设读这个 skill 的人或 agent完全不了解你的项目背景。把所有隐含知识都显式写出来。3.2 触发机制agent 怎么知道该用哪个 skill这是很多人困惑的地方。你写了一堆 skillagent 怎么知道当前任务该用哪个目前主流的触发机制有两种一种是基于描述的匹配。你在 skill 的元信息里写一段描述agent 根据当前对话的上下文去匹配最相关的 skill。这种方式灵活但不够精确有时候会匹配错。另一种是基于显式调用。你在对话里直接说“用 XX skill 来做这件事”agent 就会加载对应的 skill。这种方式精确但需要你记住 skill 的名字。实际使用中两种方式往往是混合的。我的经验是对于高频使用的 skill写好描述让它自动触发对于低频或需要精确控制的 skill手动调用。这里有个小技巧skill 的描述要写得“像人话”。我见过有人把描述写成“执行代码质量分析流程”这种描述 agent 很难判断什么时候该用。改成“当用户要求审查代码、检查代码质量、或者提交代码前需要做检查时使用”匹配准确率会高很多。3.3 工具选型写 skill 需要哪些配套工具写 skill 本身不需要什么特殊工具一个文本编辑器就够了。但要让 skill 跑起来你需要一套运行环境。根据我的经验下面这些工具是绕不开的AI 编程助手Claude Code、Codex、或者你用的其他 agent 平台。这是 skill 的运行载体。版本控制Git。skill 文件也需要版本管理尤其是团队协作的时候。测试工具用来验证 skill 是否按预期工作。可以是简单的脚本也可以是专门的测试框架。文档工具用来记录 skill 的使用方法和注意事项。别小看这个skill 多了之后没有文档你会疯掉。如果你是在 Windows 上折腾 Claude Code可能会遇到一些环境配置的问题。我建议先在 WSL 或者 Linux 环境里跑通再考虑迁移到 Windows 原生环境。Ubuntu 配置 Claude Code 的教程网上很多照着做基本没问题。3.4 注意事项这些坑我替你踩过了坑一skill 不是越多越好。我一开始兴致勃勃写了十几个 skill结果 agent 每次加载都要花时间匹配反而拖慢了响应速度。后来精简到五六个核心 skill效率明显提升。建议只写你真正高频使用的 skill。坑二skill 的粒度要适中。太粗的 skill比如“帮我写代码”等于没写太细的 skill比如“检查变量命名”又会导致 skill 数量爆炸。我的经验是一个 skill 对应一个完整的任务单元比如“代码审查”、“测试生成”、“文档撰写”。坑三skill 需要维护。你的项目在变skill 也要跟着变。我见过有人写了 skill 之后就再也不管了结果半年后 skill 里的流程跟实际项目完全对不上agent 执行出来的结果全是错的。建议把 skill 文件纳入代码仓库跟代码一起维护。4. 实操过程与核心环节实现4.1 环境准备从零开始搭建 skills 运行环境假设你是个新手想从零开始体验 skills。下面是我推荐的步骤第一步选一个 AI 编程助手。如果你主要写代码Claude Code 和 Codex 都是不错的选择。Claude Code 的 skills 生态目前更成熟一些Codex 在代码生成方面有优势。选哪个看你自己的需求。第二步安装和配置。以 Claude Code 为例安装过程不算复杂但有几个点要注意# 检查 Node.js 版本建议 18 以上 node --version # 安装 Claude Code具体命令以官方文档为准 npm install -g anthropic-ai/claude-code # 验证安装 claude --version安装完成后你需要配置 API 密钥或者登录账号。这一步可能会遇到网络问题建议提前准备好稳定的网络环境。第三步创建你的第一个 skill。在项目根目录下创建一个skills文件夹然后在里面新建一个 skill 文件。文件名建议用英文内容可以用中文。第四步测试 skill。启动 Claude Code在对话里触发你的 skill看看它是否按预期执行。如果不对检查 skill 的描述和流程是否清晰。4.2 写一个完整的 skill以“代码审查”为例下面我以一个实际的“代码审查”skill 为例展示完整的编写过程。首先确定这个 skill 的边界它只负责审查代码不负责修改代码。审查维度包括命名规范、错误处理、边界条件、性能隐患、安全问题。然后写元信息--- name: code-review description: 当用户要求审查代码、检查代码质量、或者提交代码前需要做检查时使用 ---接下来是执行流程。这部分要写得足够详细## 执行流程 1. 读取用户指定的代码文件或代码片段 2. 按以下维度逐一检查 - 命名规范变量、函数、类名是否清晰且符合项目约定 - 错误处理是否有未捕获的异常、是否有静默失败 - 边界条件空值、越界、并发等情况是否处理 - 性能隐患是否有不必要的循环、重复计算、内存泄漏风险 - 安全问题是否有注入风险、敏感信息泄露 3. 对每个发现的问题标注严重程度高/中/低 4. 生成审查报告包含问题列表和修改建议 5. 如果用户要求可以直接生成修改后的代码最后加一个示例## 示例 输入审查以下 Python 函数 输出审查报告包含发现的问题和修改建议写完这个 skill 之后我在实际项目里测试了几次。第一次测试发现 agent 只检查了命名规范其他维度都跳过了。我回去看 skill 文件发现流程里虽然写了五个维度但没有明确说“每个维度都要检查”。改成“按以下五个维度逐一检查每个维度都必须给出结论”之后问题解决了。4.3 参数计算与选择怎么确定 skill 的触发阈值有些 skill 需要设置触发阈值比如“当代码行数超过多少时触发”、“当检测到特定关键词时触发”。这个阈值怎么定我的经验是先用保守值再根据实际使用情况调整。比如你写了一个“性能优化”skill一开始可以设置“当代码中有循环嵌套超过两层时触发”。跑一段时间后如果发现漏报太多就降低阈值如果误报太多就提高阈值。这里有个计算公式可以参考触发阈值 基准值 × (1 误报率 - 漏报率)基准值是你凭经验设定的初始值误报率和漏报率根据实际使用情况统计。这个公式不是精确科学但能帮你有个调整的方向。4.4 实操现场记录一次完整的 skill 调试过程上周我在调试一个“测试生成”skill记录一下过程供你参考。问题现象agent 生成的测试用例只覆盖了正常路径没有覆盖异常路径。排查过程检查 skill 文件发现流程里写了“生成测试用例”但没有明确要求覆盖异常路径。修改 skill在流程里加上“必须包含至少一个异常路径的测试用例”。重新测试发现 agent 确实生成了异常路径的测试但异常类型不对。再次修改 skill加上“异常路径要覆盖空输入、类型错误、边界值”。第三次测试通过。经验总结skill 的流程描述要具体到“可执行”的程度。什么叫“可执行”就是 agent 读完这句话不需要再做任何猜测就能直接动手。如果你写“生成好的测试用例”agent 会困惑什么叫“好”如果你写“生成包含正常路径和异常路径的测试用例异常路径至少覆盖空输入、类型错误、边界值三种情况”agent 就能直接执行。5. 常见问题与排查技巧实录5.1 skill 不触发怎么办这是最常见的问题。你写了一个 skill但在对话里怎么试都不触发。排查思路如下先检查描述是否匹配。你的 skill 描述里写的触发条件和你实际说的那句话语义上是否一致比如你描述里写“当用户要求审查代码时使用”但你实际说的是“帮我看看这段代码有没有问题”语义上是匹配的但关键词不完全一样。有些 agent 的匹配机制比较严格可能需要你调整描述。再检查 skill 文件的位置。不同平台对 skill 文件的存放位置要求不同。Claude Code 通常要求放在项目根目录的特定文件夹下Codex 可能有不同的要求。位置不对agent 根本发现不了。最后检查 skill 文件格式。元信息的格式是否正确有没有拼写错误YAML 格式对缩进很敏感一个空格错了就可能导致解析失败。5.2 skill 执行结果不符合预期怎么办如果 skill 触发了但执行结果不对排查思路如下问题类型可能原因解决方法步骤遗漏流程描述不够明确把每一步拆得更细加上“必须执行”的强调顺序错误流程步骤有依赖关系但没说明在流程里标注步骤间的依赖关系输出格式不对没有明确输出格式要求在 skill 里加上输出格式示例工具调用失败工具依赖没配置好检查工具是否安装、权限是否足够我遇到最多的是“步骤遗漏”。agent 执行 skill 的时候如果某一步描述得不够明确它可能会跳过。解决办法很简单在每一步前面加上序号并在流程开头写上“必须按顺序执行以下所有步骤”。5.3 多个 skill 冲突怎么办当你写了多个 skill 之后可能会遇到 skill 之间冲突的情况。比如你有一个“代码审查”skill 和一个“代码重构”skillagent 在审查代码的时候可能会误触发重构 skill。解决思路有两个一是明确边界。在 skill 描述里写清楚“这个 skill 只做审查不做修改”。如果 agent 想修改代码应该触发另一个 skill。二是设置优先级。有些平台支持给 skill 设置优先级高优先级的 skill 会先被匹配。你可以把更具体的 skill 设成高优先级更通用的设成低优先级。5.4 独家避坑技巧技巧一给 skill 写“反例”。除了写“这个 skill 做什么”还要写“这个 skill 不做什么”。比如“代码审查”skill 里可以写“这个 skill 不负责修改代码如果需要修改请使用代码重构 skill”。这样能有效减少误触发。技巧二用版本号管理 skill。在 skill 文件名或元信息里加上版本号比如code-review-v2.md。这样当你更新 skill 的时候可以保留旧版本作为备份出问题了随时回滚。技巧三定期清理不用的 skill。我每季度会检查一次 skill 列表把三个月内没用过的 skill 归档。skill 太多不仅影响匹配效率还会让你自己都记不清有哪些能力可用。技巧四skill 的测试要自动化。如果你有多个 skill手动测试每个 skill 会很累。可以写一个简单的测试脚本自动触发每个 skill 并检查输出。这样每次修改 skill 之后跑一遍测试能快速发现回归问题。6. 进阶玩法从单个 skill 到 skill 组合6.1 什么是 skill 组合单个 skill 能解决单一任务但实际工作往往需要多个任务串联。比如“开发一个新功能”这个任务可能涉及需求分析 → 代码编写 → 代码审查 → 测试生成 → 文档撰写。如果每个环节都是一个 skill把它们串起来就是一个 skill 组合。skill 组合的好处是你只需要说“开发一个新功能”agent 会自动按顺序调用相关 skill。这比你自己一步步指挥效率高得多。6.2 怎么设计 skill 组合设计 skill 组合的关键是定义清楚 skill 之间的输入输出关系。比如“代码编写”skill 的输出是代码文件“代码审查”skill 的输入是代码文件。这两个 skill 就能串起来。我通常会用一张表来梳理 skill 组合步骤skill 名称输入输出依赖1需求分析用户描述需求文档无2代码编写需求文档代码文件步骤13代码审查代码文件审查报告步骤24测试生成代码文件测试文件步骤25文档撰写代码文件需求文档文档步骤2有了这张表你就可以在 agent 里配置一个“开发工作流”skill让它按这个顺序调用各个子 skill。6.3 组合 skill 的注意事项注意一错误处理。如果步骤3的代码审查发现了严重问题应该回退到步骤2重新编写而不是继续往下走。你需要在组合 skill 里定义清楚什么情况下回退、什么情况下继续。注意二上下文传递。步骤2的输出要能顺利传给步骤3。如果步骤2输出的代码文件路径和步骤3期望的输入格式不一致就会出问题。建议在组合 skill 里统一定义数据格式。注意三性能考虑。组合 skill 会调用多个子 skill每次调用都有开销。如果子 skill 太多整体响应时间会很长。我的经验是一个组合 skill 包含的子 skill 不要超过7个否则考虑拆分成多个组合。7. 我个人的一些经验和建议折腾 skills 这半年多我最大的感受是这东西的上限很高但前提是你愿意花时间打磨。我见过很多人装完 Claude Code 或者 Codex随便试了两下觉得“也就那样”就放弃了。其实问题不在工具在于他们没有把 skill 写好。我的建议是从一个最小的 skill 开始。不要一上来就想搭建完整的工作流先写一个最简单的 skill比如“代码格式化检查”跑通整个流程。然后逐步增加复杂度写第二个、第三个 skill最后再考虑组合。另外不要闭门造车。社区里有很多人分享了自己的 skill 文件你可以参考他们的写法。我刚开始写 skill 的时候就是从别人的 skill 文件里学到的结构设计和描述技巧。当然参考不等于照搬你要根据自己的项目特点做调整。最后说一个我最近在尝试的方向把 skill 和本地模型结合起来。比如用 Claude Code 调用 LMStudio 的本地模型来执行某些 skill这样既能享受 skill 的便利又能控制成本。这个方向还在摸索中等有成熟经验了再跟大家分享。如果你也在折腾 skills欢迎交流。踩过的坑、好用的技巧、有意思的玩法都可以聊。毕竟这东西还在快速演进多交流才能少走弯路。