1. 从“skills”这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你随便翻翻热搜词列表就能看到skills、Claude Code、Codex、plugin、agents、find skills、skills推荐、codex skills、claude agent skills……这些词扎堆出现说明一件事围绕 AI 编程助手的能力扩展正在从“模型本身有多强”转向“怎么让模型按我的方式干活”。我最早接触这个概念是在折腾 Claude Code 的时候。当时我的诉求特别朴素每次让 AI 帮我写代码它都要重新理解一遍我的项目结构、代码规范、提交习惯烦得要命。后来发现 Claude Code 支持一种叫 skills 的机制可以把这些“重复交代的上下文”固化下来变成一个可复用的能力单元。再后来 Codex 也跟进了类似的设计plugin、agents 这些词开始混在一起用很多人就懵了——skills 到底是什么它和 plugin、agent 有什么区别为什么有人把它叫“superpower skills”用一句话说清楚skills 是给 AI 编程助手用的“技能包”把特定场景下的指令、工具调用、上下文约束打包成一个可被自动识别和加载的模块。你可以把它理解成给 AI 装的一个“插件”但比传统插件更轻、更偏“行为指导”而不是“功能扩展”。它解决的问题是让 AI 在特定任务上表现得更像“一个懂行的老手”而不是“一个什么都知道一点但什么都不精的实习生”。这篇文章适合谁看如果你是刚接触 Claude Code 或 Codex 的新手想搞清楚 skills 到底怎么装、怎么用、怎么自己写那这篇就是给你准备的。如果你已经在用这些工具但总觉得“AI 干活不够顺手”那 skills 很可能就是你缺的那块拼图。下面我会从设计思路、核心机制、实操步骤、常见坑四个层面把这件事讲透。2. skills 的整体设计与思路拆解2.1 为什么是“技能”而不是“插件”或“代理”先厘清一个容易混淆的点。plugin插件通常指的是给宿主程序增加新功能的模块比如给 IDE 加一个代码格式化按钮。agent代理通常指的是一个能自主规划、调用工具、完成多步任务的智能体。而 skills 的定位介于两者之间它不增加新功能也不自主规划它做的是“在特定场景下告诉 AI 应该怎么思考、怎么调用已有工具、遵守什么约束”。这个定位非常关键。我见过不少人一上来就想用 skills 实现“自动帮我部署上线”结果发现 skills 根本不做这种事——那是 agent 的活。skills 更像是一份“岗位说明书”当用户提出某类需求时AI 应该按照这份说明书里的流程、规范、注意事项来执行。比如一个“代码审查 skill”它不会帮你改代码但它会告诉 AI审查时要先看命名规范再看边界条件最后看测试覆盖输出格式必须是“问题-位置-建议”三段式。为什么这样设计因为大模型的能力已经足够强缺的不是“能不能做”而是“做得稳不稳、符不符合我的要求”。skills 通过约束输入和输出把 AI 的行为收敛到一个可控范围内。这比训练一个专用模型便宜得多也比写一堆 prompt 模板优雅得多。2.2 skills 和 Claude Code、Codex 的关系Claude Code 和 Codex 是两个不同的 AI 编程助手产品但它们在 skills 这件事上的思路高度一致都支持通过文件或配置定义技能都支持在对话中自动或手动触发技能都强调技能的可组合性。区别在于实现细节和生态成熟度。Claude Code 的 skills 更偏向“项目级配置”你可以在项目根目录放一个 skills 目录里面按技能名组织文件AI 在读取项目上下文时会自动加载。Codex 的 skills 则更偏向“会话级配置”你可以在对话开始时指定启用哪些技能或者通过 plugin 机制动态加载。热搜词里出现的codex skills、claude agent skills、find skills这些本质上都是在问“怎么找到、怎么装、怎么用”。还有一个热词叫superpower skills这个说法我最早是在一些开发者分享里看到的。它指的其实不是某个官方功能而是把多个基础 skill 组合成一个高阶 skill让 AI 在复杂任务上表现出“超能力”。比如把“读代码”“写测试”“跑测试”“改代码”四个 skill 串起来形成一个“自动修复测试失败”的 superpower skill。这个思路很实用后面我会专门讲怎么组合。2.3 方案选型为什么用文件而不是数据库如果你去看 Claude Code 或 Codex 的 skills 实现会发现它们几乎都用文件系统来存储技能定义而不是数据库或远程服务。这个选择背后有几个考量。第一可版本控制。技能定义是文本文件可以跟着项目一起提交到 Git团队成员拉下来就能用变更历史一目了然。第二可读可改。开发者可以直接用编辑器打开技能文件改一行保存就生效不需要重启服务或重新编译。第三低耦合。技能文件不依赖特定运行时换一个 AI 助手只要格式兼容就能复用。第四便于分享。热搜词里skills推荐、find skills说明大家有分享和发现技能的需求文件形式天然适合打包和分发。我实测下来这种设计在团队协作场景下优势特别明显。我们团队把代码规范、提交信息格式、review 清单都写成了 skill 文件新同事入职第一天拉下代码AI 助手就自动按团队规范干活省掉了大量“口头交代”的成本。3. 核心细节解析与实操要点3.1 skill 文件的基本结构不同工具的 skill 文件格式略有差异但核心字段大同小异。以 Claude Code 为例一个典型的 skill 文件通常包含以下几个部分name技能名称用于触发和引用建议用英文小写加连字符比如code-review。description技能描述AI 用它来判断什么时候该加载这个技能所以要写得具体包含触发场景关键词。instructions核心指令告诉 AI 具体怎么做可以包含步骤、约束、输出格式。tools可选声明这个技能会用到哪些工具比如读文件、跑命令。examples可选给几个输入输出示例帮助 AI 理解预期行为。Codex 的格式更偏向 JSON 或 YAML 配置字段名可能叫id、trigger、actions但逻辑是一样的。我建议你先从官方文档给的模板改起不要一上来就自己造格式容易踩兼容性的坑。注意description 字段是触发准确率的关键。写得太宽泛AI 会在不相关场景乱加载写得太窄该用的时候又不触发。我的经验是description 里至少包含“什么时候用”和“解决什么问题”两个信息。3.2 触发机制自动还是手动skills 的触发方式主要有两种自动触发和手动触发。自动触发靠的是 AI 对用户输入和 description 的语义匹配比如你说“帮我看看这段代码有没有问题”AI 匹配到code-review技能的 description 里有“代码审查”“问题检查”等词就会自动加载。手动触发则是用户显式指定比如在 Claude Code 里输入/skill code-review或者在 Codex 里用skill语法。两种方式各有适用场景。自动触发适合高频、通用的技能比如代码格式化、命名规范检查。手动触发适合低频、需要明确意图的技能比如“生成数据库迁移脚本”这种一旦误触发后果比较严重的。我个人的做法是通用技能开自动危险技能只开手动。这样既省事又安全。还有一个细节多个技能同时被触发时加载顺序会影响结果。Claude Code 默认按技能名称字母序加载Codex 默认按声明顺序加载。如果你有技能之间存在依赖比如test-fix依赖run-test那就要在配置里显式声明依赖关系或者干脆合并成一个技能。3.3 技能的组合与复用单个技能能做的事有限真正体现威力的是组合。热搜词里superpower skills说的就是这个。组合方式有两种串行组合和并行组合。串行组合是把多个技能按顺序执行前一个的输出作为后一个的输入。比如“读代码 → 找问题 → 改代码 → 跑测试”就是典型的串行。并行组合是多个技能同时作用于同一个输入比如“安全检查”和“性能检查”可以同时跑最后合并结果。实现组合的关键是定义清楚技能之间的接口。如果find-bug技能输出的是自然语言描述而fix-bug技能期望的是结构化的问题列表那组合就会失败。我的做法是在技能定义里明确写出输入格式和输出格式最好用 JSON schema 约束。这样组合起来就像搭积木不会出现“插不上”的情况。提示组合技能时建议先用小规模任务验证接口是否匹配再放到大任务上跑。我踩过一次坑两个技能单独跑都没问题组合起来因为输出格式差了一个字段导致整个流程卡死排查了半天。3.4 技能的市场与发现热搜词里find skills、skills推荐、claude 国内安装skills 官方市场这些反映的是大家对“去哪找现成技能”的需求。目前 Claude Code 和 Codex 都有官方的技能市场或示例库社区也有不少人在分享自己写的技能。找技能的渠道主要有几个官方文档的示例库、GitHub 上的 awesome-skills 类仓库、技术社区里的分享帖。我建议优先用官方示例因为格式和兼容性最有保障。社区技能质量参差不齐用之前一定要看 description 和 instructions确认没有奇怪的依赖或危险操作。安装技能的方式通常是下载技能文件放到项目的 skills 目录或者通过命令行工具安装。热搜词里dsh plugin --profile web add dshmarket这种命令就是某种技能管理工具的安装指令。不同工具命令不同但思路一样把技能文件放到 AI 助手能读到的位置。4. 实操过程与核心环节实现4.1 环境准备Claude Code 和 Codex 的安装在折腾 skills 之前得先把宿主工具装好。Claude Code 和 Codex 的安装方式不太一样我分别说一下。Claude Code 的安装官方推荐用 npm 全局安装npm install -g anthropic-ai/claude-code装完之后在项目目录下运行claude就能启动。如果你在 Windows 上建议用 WSL 或者 Git Bash原生 CMD 有时候会有路径问题。热搜词里claude code windows、claude code安装、ubuntu配置claude code这些说明跨平台安装是大家常问的。我的经验是Linux 和 macOS 最省心Windows 用 WSL 最稳。Codex 的安装官方提供了安装包和命令行两种方式。命令行方式通常是npm install -g openai/codex或者从官网下载对应平台的安装包。热搜词里codex安装包、codex下载、codex官网下载、codex安装教程出现频率很高说明很多人卡在第一步。这里提醒一句一定要从官方渠道下载第三方渠道的安装包有被篡改的风险。装完之后需要登录。Claude Code 用 Anthropic 账号登录Codex 用 OpenAI 账号登录。热搜词里codex登录、your organization has disabled claude subscription access这些反映的是登录和权限问题。如果遇到组织禁用的情况需要联系管理员开通或者用个人账号。4.2 创建第一个 skill从代码审查开始环境准备好之后我们来创建一个最简单的 skill代码审查。这个技能的目标是让 AI 在你说“审查代码”时按照固定流程检查代码并输出结构化结果。第一步在项目根目录创建 skills 目录mkdir -p .claude/skills不同工具的技能目录名可能不同Claude Code 默认是.claude/skillsCodex 可能是.codex/skills具体看官方文档。第二步创建技能文件code-review.md--- name: code-review description: 当用户要求审查代码、检查代码问题、review 代码时使用。适用于函数、类、模块级别的代码审查。 tools: - read_file - search_code --- # 代码审查流程 1. 先通读代码理解整体意图。 2. 检查命名规范变量、函数、类名是否清晰达意。 3. 检查边界条件空值、越界、异常路径是否处理。 4. 检查错误处理异常是否被捕获错误信息是否有用。 5. 检查测试覆盖关键路径是否有测试。 6. 按以下格式输出 - 问题一句话描述 - 位置文件:行号 - 建议具体修改建议第三步保存文件然后在对话里说“帮我审查一下这个文件”AI 应该会自动加载这个技能并按流程执行。这里有几个细节要注意。description 里要包含触发词比如“审查”“检查”“review”这样 AI 才能匹配到。instructions 要分步骤不要写成一大段AI 对有序列表的理解更准确。输出格式要明确否则 AI 每次输出的结构都不一样没法程序化处理。4.3 参数计算与选择技能粒度怎么定技能粒度是个很容易踩坑的地方。粒度太粗一个技能干太多事AI 容易漏步骤粒度太细技能太多触发和管理都麻烦。我的经验是一个技能对应一个明确的、可独立验证的任务。怎么判断“可独立验证”就是你能用一句话说清楚“这个技能做完之后怎么算成功”。比如“代码审查”技能成功标准是“输出了结构化的问题列表”。“跑测试”技能成功标准是“测试命令执行完毕并返回结果”。如果一个技能的成功标准说不清楚那说明粒度不对需要拆分或合并。具体到数量一个项目里 5 到 15 个技能是比较舒服的区间。少于 5 个说明很多重复工作没被固化多于 15 个说明拆得太细管理成本超过收益。当然这只是参考具体看项目复杂度。还有一个参数是技能加载的优先级。当多个技能同时匹配时哪个先加载Claude Code 支持在技能文件里设置priority字段数字越小优先级越高。我一般把“安全相关”的技能设成最高优先级确保不会被其他技能覆盖。4.4 技能调试怎么知道技能生效了技能写完不是就完事了得验证它真的生效。Claude Code 和 Codex 都提供了调试模式可以看到当前加载了哪些技能、触发了哪些指令。Claude Code 里可以用--debug参数启动或者在对话里输入/debug查看当前技能状态。Codex 里通常有--verbose参数。如果看不到技能加载日志说明技能没被识别可能是文件路径不对、格式有误、或者 description 没匹配上。我常用的排查步骤是先确认文件在正确的目录下再确认文件格式符合规范然后手动触发一次看是否生效最后检查 description 是否包含用户输入的关键词。这四步走下来九成问题都能定位。注意技能文件修改后有些工具需要重启会话才能生效有些是热加载。Claude Code 默认是热加载改完保存即可Codex 有些版本需要重启。不确定的话重启一次最保险。5. 常见问题与排查技巧实录5.1 技能不触发怎么办这是最高频的问题。技能写好了但 AI 就是不用。原因通常有三个description 没匹配上、文件路径不对、格式有误。description 没匹配上是最常见的。AI 判断是否加载技能靠的是把你的输入和 description 做语义匹配。如果你说“帮我看看这段代码”而 description 里只写了“代码审查”那可能匹配不上。解决办法是在 description 里多写几个同义词和场景词比如“审查、检查、review、看看代码、代码问题”。文件路径不对也很常见。不同工具的技能目录不一样Claude Code 是.claude/skillsCodex 可能是.codex/skills或skills。放错目录 AI 读不到。建议先用官方示例确认目录结构再放自己的技能。格式有误通常是 YAML frontmatter 写错了比如冒号后面没空格、缩进不对、字段名拼错。这种问题用编辑器的 YAML 插件能提前发现。5.2 技能冲突与覆盖多个技能同时触发时可能会出现指令冲突。比如一个技能说“输出用 JSON”另一个说“输出用 Markdown”AI 就懵了。解决办法有两个一是设置优先级高优先级技能覆盖低优先级二是合并技能把冲突的部分抽出来做成一个基础技能其他技能引用它。我倾向于第二种因为优先级机制虽然简单但多了之后很难维护谁覆盖谁容易搞混。还有一个隐蔽的冲突是工具调用冲突。两个技能都声明要用run_command但一个要跑测试一个要跑构建同时触发时可能互相干扰。这种情况建议把工具调用也纳入技能组合的接口定义明确谁先谁后。5.3 技能性能问题技能多了之后AI 的响应会变慢。因为每次对话都要加载和匹配所有技能技能越多匹配开销越大。优化方法有几个按需加载不要把所有技能都放在项目根目录可以按模块分目录AI 只加载当前模块相关的技能。精简 descriptiondescription 越长匹配越慢控制在 100 字以内比较合适。定期清理半年没用过的技能就删掉别留着占地方。我实测下来一个项目里技能数量控制在 10 个左右时响应速度基本无感。超过 20 个就能感觉到明显延迟了。5.4 常见问题速查表问题现象可能原因排查方法解决办法技能不触发description 未匹配检查 description 是否含用户输入关键词补充同义词和场景词技能不触发文件路径错误确认技能文件在正确目录参考官方文档调整路径技能不触发格式有误检查 YAML frontmatter用 YAML 校验工具检查技能冲突指令矛盾查看调试日志确认加载了哪些技能设置优先级或合并技能响应变慢技能过多统计技能数量按需加载、精简 description输出格式不稳定instructions 不明确检查输出格式定义用 JSON schema 约束输出技能修改不生效未热加载确认工具是否支持热加载重启会话5.5 独家避坑技巧最后分享几个我踩过坑之后总结的技巧。技巧一技能文件用英文命名内容用中文写。文件名用英文是为了跨平台兼容避免编码问题内容用中文是因为 AI 对中文指令的理解在中文场景下更准确。当然如果你的团队用英文那就全英文。技巧二每个技能都写一个最小示例。在技能文件里加一个examples字段给一个输入和一个期望输出。这样不仅 AI 理解更准你自己调试时也有参照。技巧三技能版本化。技能文件跟着项目走 Git每次修改都提交这样出问题可以回滚。我见过有人直接在生产环境改技能文件改坏了没法恢复只能重写。技巧四危险操作加确认。如果技能会执行删除、覆盖、部署等危险操作在 instructions 里明确要求 AI 先输出计划并等待确认。这个习惯救过我好几次。技巧五定期 review 技能。技能不是写完就完了项目在变技能也要跟着变。我一般每个月花半小时过一遍所有技能删掉过时的更新不准确的。这个投入产出比很高。6. 技能生态的延伸玩法6.1 把技能接入本地模型热搜词里claude code 调用lmstudio的本地模型、codex接入deepseek这些反映的是大家想把 skills 机制和本地模型结合的需求。思路其实不复杂Claude Code 和 Codex 都支持配置自定义的模型端点你把端点指向本地运行的模型服务技能机制照样能用。具体操作上Claude Code 可以通过环境变量或配置文件指定 API 地址Codex 也有类似的配置项。本地模型用 LM Studio、Ollama 之类的工具跑起来暴露一个兼容的 API 接口然后在 Claude Code 或 Codex 里把地址指过去就行。这里要注意的是本地模型的指令遵循能力通常不如云端大模型技能里的复杂指令可能会被忽略。我的建议是本地模型配简单技能复杂技能还是用云端模型。或者把复杂技能拆成多个简单技能逐步执行。6.2 技能与 agents 的配合热搜词里langchain deep agents、agents anywhere这些说的是 agent 框架。skills 和 agents 不是竞争关系而是互补关系。agent 负责规划和调度skills 负责具体执行。你可以把 skills 看成 agent 的“工具箱”agent 决定用哪个工具skills 定义工具怎么用。实际配合时agent 框架通常支持注册自定义工具你可以把 skill 包装成一个工具注册进去。这样 agent 在规划时就能看到这个技能需要时调用。这种模式在复杂任务上特别有用比如“自动修复 bug”这种需要多步规划的任务agent 负责拆解步骤skills 负责每步的具体执行。6.3 技能的安全考量技能本质上是给 AI 的指令如果技能文件被恶意篡改AI 可能会执行危险操作。所以技能文件的安全管理很重要。我的做法是技能文件纳入代码审查流程任何人修改技能都要经过 review。敏感技能加签名用 GPG 签名验证文件完整性。限制技能权限只给必要的工具权限比如只读技能就不给写权限。定期审计检查技能文件是否有异常修改。热搜词里agentpoison: red-teaming llm agents via poisoning memory or knowledge ba这个说的就是通过污染 agent 的记忆或知识库来攻击。技能文件如果被污染效果类似。所以安全这根弦不能松。7. 我个人的一些实操体会折腾 skills 这半年最大的感受是它把“提示词工程”从一次性消耗品变成了可积累的资产。以前写 prompt 是即用即弃现在写 skill 是越攒越多团队里每个人都能受益。这个转变的价值比单个技能能干什么大得多。另一个体会是技能的质量比数量重要。我一开始贪多写了三十多个技能结果触发混乱、维护困难最后砍到十二个反而好用多了。现在我的标准是一个技能如果一个月内没被触发过就考虑删掉。还有一点不要指望技能解决所有问题。技能能固化流程、约束输出但它不能替代清晰的思考。如果你自己都没想清楚一个任务该怎么拆解写成技能也是糊的。先想清楚再写技能顺序不能反。最后分享一个小技巧技能文件里加一个“反例”字段写明什么情况下不要用这个技能。这个字段对减少误触发特别有效。比如代码审查技能里写“不要用于审查配置文件”AI 就不会在你看 YAML 的时候跳出来审查了。这个技巧我是从一次误触发事故里总结出来的当时 AI 在我改 CI 配置时自动触发了代码审查输出了一堆无关建议浪费了不少时间。加上反例字段之后这类问题再没出现过。