1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。你随便翻一下热搜词列表就能看到claude code skills、codex skills、agent skills测试、好用的skills、skills开发、写论文的skills……一大堆。很多人第一次看到会懵这跟“技能”有什么关系是某种新出的插件吗还是某个框架的功能模块我一开始也以为是营销概念直到自己动手在 Claude Code 和 Codex 里跑通了几套 skills才意识到这东西确实解决了一个非常具体的痛点让 AI 编程助手从“每次都要重新解释一遍需求”变成“一次定义、反复调用、行为稳定”。你可以把它理解成给 AI 助手写的“操作手册”或者“岗位说明书”——你告诉它遇到某类任务时该按什么流程走、该调用哪些工具、该遵守哪些约束它就会像一个训练有素的员工一样去执行而不是每次自由发挥。这个项目标题就叫“skills”看起来简单但它背后牵扯的东西非常多Claude Code 的 skills 机制、Codex 的 skills 配置、agents 的协作方式、plugin 的加载逻辑甚至包括本地模型接入、代理配置失败排查、插件仓库地址设置这些实操层面的坑。热词里还混进了cc switch local proxy failed while handling codex endpoint /responses、codex is ignoring 1 unrecognized configuration setting、your organization has disabled claude subscription access这类报错信息说明大量开发者在真实使用中卡在了配置和权限环节。所以这篇内容我打算按一个完整项目来拆从 skills 的核心设计思路讲起然后拆解 Claude Code 和 Codex 两套体系下 skills 的具体写法、目录结构、加载机制再进入实操环节把安装、配置、调试、排查的完整流程走一遍最后把我踩过的坑和常见报错整理成速查表。适合已经装过 Claude Code 或 Codex、但还没真正把 skills 用起来的开发者也适合刚接触 agents 概念、想搞清楚“skills 和 plugin 到底有什么区别”的新手。你不需要是 AI 专家但最好有一点命令行基础和配置文件编辑经验。2. skills 的整体设计与核心思路拆解2.1 skills 和 plugin、agent 到底有什么区别很多人把这三个概念混着用其实它们的分工非常清晰。我用一个生活化的类比来解释假设你开了一家餐厅agent 是厨师负责实际做菜plugin 是厨房里的设备比如烤箱、搅拌机提供能力skills 是菜谱告诉厨师遇到“红烧肉”这个需求时该先焯水、再炒糖色、然后小火炖多久。没有菜谱厨师也能做但每次味道可能不一样有了菜谱出品就稳定了。在 Claude Code 的体系里skill 本质上是一个带有元数据的指令包通常以目录或文件形式存在里面包含触发条件、执行步骤、可用工具列表和输出格式要求。Codex 那边的 skills 更偏向于“可复用的任务模板”通过配置文件注册后在对话中通过特定指令唤起。两者实现细节不同但核心思想一致把重复性的、有固定流程的任务从“每次口头描述”变成“结构化定义”。热词里出现的claude agent skills: a first principles deep dive和superpower skills其实就是在讨论这个分层设计。我自己的理解是skills 的价值不在于让 AI 变聪明而在于让 AI 变“可控”。你定义得越细它的行为就越可预测这在生产环境里比“偶尔惊艳”重要得多。2.2 为什么现在大家都在做 skills一个直接原因是模型能力上来了但“会用工具”和“会按流程办事”是两回事。你让 Claude Code 帮你写一个 React 组件它能写但你让它“按照我们团队的规范先写测试、再写实现、最后跑 lint 并生成变更说明”如果不给 skill它每次的步骤顺序、文件命名、注释风格都可能不一样。skills 就是把这个流程固化下来。另一个原因是 agents 的普及。热词里有agents anywhere、langchain deep agents说明大家开始让多个 agent 协作。多个 agent 协作时如果没有统一的 skill 定义沟通成本会爆炸。每个 agent 都按自己的理解做事最后合起来就是一团乱。skills 在这里扮演的是“接口协议”的角色让不同 agent 对同一类任务有共同的行为预期。还有一个很现实的原因成本。你每次在对话里详细描述需求消耗的是 token把需求写成 skill只在触发时加载长期看省的是真金白银。尤其是团队协作场景一个人写好 skill所有人都能复用边际成本几乎为零。2.3 一套 skill 的基本结构应该包含什么根据我在 Claude Code 和 Codex 里的实际使用经验一个能用的 skill 至少包含这几块触发描述什么情况下用这个 skill、前置条件需要哪些文件、环境、权限、执行步骤按顺序做什么、工具约束允许调用哪些工具、禁止做什么、输出规范结果以什么格式返回、异常处理遇到某类错误怎么退避。这六块缺一块skill 的稳定性就会打折扣。我见过很多人写 skill 只写执行步骤结果 AI 在不满足前置条件时硬跑报一堆错。也有人不写工具约束AI 为了完成任务去调用不该调用的接口。这些坑后面我会在排查章节详细展开。这里你先记住一个原则skill 是给“严格执行者”看的不是给“聪明人”看的。你写得越明确它执行得越稳。3. Claude Code 体系下 skills 的核心细节与实操要点3.1 Claude Code 的安装与基础环境确认在写 skill 之前得先把 Claude Code 跑起来。热词里claude code安装、claude code下载、claude code windows、ubuntu配置claude code、vscode配置claude code全是围绕这一步的。我分别在 Windows 和 Ubuntu 上装过流程大同小异但有几个细节容易卡住。Windows 下建议用官方提供的安装方式装完后确认claude命令能在终端里直接调用。如果提示找不到命令大概率是 PATH 没刷新重开一个终端或者手动把安装目录加进去。Ubuntu 下要注意权限问题不要用 root 直接跑建议普通用户安装后在用户级目录配置。VS Code 里配置 Claude Code 的话重点是确认扩展加载的终端环境和系统终端一致否则会出现“终端里能用、扩展里不能用”的诡异情况。提示安装完成后先跑一次claude --version确认版本再跑一次最简单的对话测试。不要一上来就配 skill基础链路没通之前任何 skill 问题都会被放大成“是不是装错了”。热词里还有claude code 调用lmstudio的本地模型这是进阶玩法。如果你想让 Claude Code 走本地模型需要在配置里指定本地服务的地址和模型名。这里的关键是确认本地服务已经启动、端口没被占用、模型名和实际加载的一致。我试过几次最常见的失败原因是模型名写错或者本地服务没开报错信息往往很模糊需要你逐项排查。3.2 skill 的目录结构与文件命名规范Claude Code 的 skill 通常放在特定的 skills 目录下每个 skill 一个子目录目录名就是 skill 的标识。我建议用“动词-名词”的命名方式比如generate-component、review-pr、write-test这样一眼能看出它是干什么的。目录里一般包含一个主定义文件描述触发条件和执行逻辑可能还有辅助的模板文件、示例文件。文件命名上有个坑不要用中文名不要用空格不要用特殊字符。我见过有人用“代码审查.skill”这种名字结果加载时直接报错。统一用英文小写加连字符这是最稳的。另外skill 目录的层级不要太深一般两层就够了太深了加载逻辑容易出问题。3.3 触发条件怎么写才不会被误触发触发条件是 skill 里最微妙的部分。写得太宽什么任务都往里套AI 会频繁调用不该调的 skill写得太窄该用的时候用不上。我的经验是用“任务类型 关键词 前置状态”三重条件来限定。举个例子你要写一个“生成 React 组件”的 skill触发条件可以写成当用户要求创建新的 React 组件且当前项目包含package.json且依赖里有 react 时触发。这样既限定了任务类型又限定了项目环境避免在 Vue 项目里误触发。热词里前端开发skills和skills推荐讨论的很多就是这类触发条件的写法。还有一个技巧在触发描述里明确写出“不适用场景”。比如“本 skill 不适用于修改已有组件仅适用于新建”。这种负向描述能显著降低误触发率。我实测下来加了负向描述之后误触发从每天好几次降到几乎为零。3.4 执行步骤的粒度控制执行步骤写多细这是新手最常问的问题。我的答案是细到“一个刚入职但很听话的实习生能照着做”的程度。不要写“优化代码”要写“读取目标文件识别重复逻辑提取为独立函数更新所有调用点运行测试确认通过”。每一步都应该是可验证的动作而不是模糊的目标。但也不要细到“按哪个键”这种程度那样 skill 会变得极其冗长加载慢、维护难。我一般控制在 5 到 12 步之间每步一句话说清楚“做什么 用什么工具 产出什么”。如果某一步特别复杂就拆成子步骤或者单独抽成另一个 skill 来调用。注意步骤之间如果有依赖关系一定要写明“上一步成功后才能执行下一步”。AI 有时候会并行执行本应串行的步骤导致中间状态混乱。明确写出依赖关系能避免这个问题。3.5 工具约束与权限边界Claude Code 的 skill 可以声明允许使用的工具范围。这一步很多人跳过觉得“反正它也不会乱来”。但实际用下来不写工具约束的 skill 在复杂任务里很容易越界。比如你只想让它读文件它可能去执行命令你只想让它改一个文件它可能顺手改了配置。我的做法是默认最小权限按需开放。skill 里明确列出允许的工具没列出的默认禁止。如果某个步骤确实需要额外权限单独在那一行注明。这样即使 AI 判断失误影响范围也可控。热词里agent skills测试和skills开发相关的讨论里权限边界是高频话题说明大家都在这上面吃过亏。4. Codex 体系下 skills 的配置与实操流程4.1 Codex 安装与登录环节的常见卡点Codex 这边的安装流程和 Claude Code 有相似之处但配置项更多。热词里codex安装、codex安装教程、codex安装包、codex下载、codex官网下载、codex登录全是这一步的搜索。我建议从官方渠道获取安装包不要用来路不明的第三方版本避免配置被篡改或者夹带额外内容。登录环节最容易出问题的是组织权限。热词里codex无法加载组织设置和your organization has disabled claude subscription access这类报错本质上是账号权限和订阅状态的问题。遇到这种先确认账号本身是否有效再确认组织管理员有没有开启对应权限。如果是个人账号检查订阅是否过期。这些属于账号层面的问题跟 skill 本身无关但会卡住整个流程所以要先排除。4.2 Codex 的配置文件结构与 skill 注册方式Codex 的 skill 注册通常通过配置文件完成。配置文件里需要声明 skill 的名称、路径、触发指令、可用范围。热词里codex is ignoring 1 unrecognized configuration setting. check for typos or d这个报错非常典型就是配置文件里写了 Codex 不认识的字段或者字段名拼错了。Codex 对配置项的校验比较严格多一个空格、少一个引号都可能被忽略。我的建议是改配置之前先备份改完用最小配置测试。不要一次性加一堆 skill先加一个确认能加载、能触发、能正常执行再加第二个。这样出问题时排查范围小。另外配置文件的缩进和格式要严格遵守YAML 对缩进敏感JSON 对逗号敏感写错了不会报明确错误只会静默忽略。4.3 Codex 接入外部模型时的 skill 行为差异热词里codex接入deepseek说明很多人想让 Codex 走第三方模型。这里要注意不同模型对 skill 指令的遵循程度不一样。我在实测中发现有些模型对结构化指令的执行很稳有些则容易“自由发挥”把 skill 里的步骤顺序打乱。如果你发现 skill 在某个模型下行为异常先换回默认模型测试确认是 skill 的问题还是模型的问题。接入外部模型时skill 里的工具调用描述要写得更明确。因为不同模型对工具的理解能力有差异模糊的描述在强模型下没问题在弱模型下就会出错。我的做法是如果确定要接外部模型skill 里的每一步都加上“使用 XX 工具执行 XX 操作”的明确说明减少模型的自主判断空间。4.4 代理配置失败与端点报错的排查思路热词里cc switch local proxy failed while handling codex endpoint /responses这个报错是本地代理在处理 Codex 请求时失败了。这类问题的排查顺序是先确认本地代理服务是否正常运行再确认端口是否被占用然后确认 Codex 配置里的端点地址和代理地址是否匹配最后看代理日志里的具体错误信息。我遇到过几次原因分别是代理服务没启动、端口冲突、配置里地址写成了旧版本、以及代理版本和 Codex 版本不兼容。排查这类问题日志是第一手信息不要靠猜。把代理的日志级别调高复现一次看它到底卡在哪一步。大部分时候日志会直接告诉你原因比盲目改配置高效得多。5. 完整实操从零写一个可用的 skill 并跑通5.1 场景选择与需求拆解我拿一个真实场景来演示自动生成单元测试并运行。这个场景足够典型涉及文件读取、代码生成、命令执行、结果判断多个环节能覆盖 skill 的大部分核心要素。需求拆解下来是给定一个源文件读取它的导出函数为每个函数生成对应的测试用例写入测试文件运行测试命令如果失败则输出失败原因如果通过则输出摘要。这个 skill 的触发条件是用户要求为某个文件生成测试且项目里有测试框架配置。前置条件是源文件存在、测试目录存在、测试命令可执行。执行步骤我规划为八步工具约束限定为文件读写和命令执行输出规范要求返回测试通过率和失败详情。5.2 skill 定义文件的编写定义文件我按前面说的六块结构来写。触发描述里明确写出“仅适用于为已有源文件生成新测试不适用于修改已有测试”。前置条件里列出需要检查的三项。执行步骤从“读取源文件”开始到“输出结果摘要”结束每步都注明使用的工具。工具约束里只开放读文件、写文件、执行测试命令三类。输出规范里定义成功和失败两种格式。异常处理里写明“如果测试框架未配置终止并提示用户”。写完后我建议先做一次“干跑”不实际执行只让 AI 复述它理解的步骤看是否和你的预期一致。这一步能提前发现描述歧义。我干跑过几次发现有些步骤我以为是串行的AI 理解成了并行调整描述后就对了。5.3 加载与触发测试把 skill 放到对应目录后重启 Claude Code 或 Codex让它重新加载。然后在一个测试项目里触发这个 skill观察它的行为。第一次跑大概率不会完美可能步骤顺序不对、可能某个工具没权限、可能输出格式不符合预期。这些都是正常的skill 开发本身就是迭代过程不要指望一次写对。我一般会跑三轮第一轮看它能不能走完全流程第二轮看每步的产出是否符合预期第三轮看异常情况下它会不会正确终止。三轮下来一个稳定的 skill 基本就成型了。热词里agent skills测试说的就是这个过程测试不是跑一次就完要覆盖正常路径和异常路径。5.4 参数计算与选择过程实录在写测试生成 skill 时有一个参数需要计算生成多少个测试用例。我的策略是按导出函数的数量来定每个函数至少一个正常用例、一个边界用例。如果函数有参数根据参数类型补充类型异常用例。这个规则我直接写进了 skill 里让 AI 按规则计算而不是自由决定。具体写的时候我用了这样的描述“统计源文件的导出函数数量 N为每个函数生成至少 2 个用例总用例数不少于 2N。如果 N 大于 10优先为前 10 个函数生成其余函数生成占位用例并标注待补充。”这样既保证了覆盖率又避免了在超大文件上生成过多用例导致超时。这个阈值 10 是我根据实际项目规模定的你可以根据自己的情况调整。6. 常见问题与排查技巧实录6.1 skill 不触发或误触发怎么排查不触发的原因通常有三个触发条件写得太窄、skill 没被正确加载、或者当前上下文不满足前置条件。排查顺序是先确认 skill 在列表里能看到再看触发描述是否覆盖了当前任务最后检查前置条件是否满足。误触发的原因通常是触发条件太宽或者缺少负向描述解决办法是加限定词和“不适用场景”。我整理了一个速查表覆盖最常见的几类问题问题现象可能原因排查动作解决方式skill 完全不触发未加载或路径错误检查 skill 列表和目录修正路径后重启偶尔触发偶尔不触发触发条件边界模糊复现触发时的上下文收窄或明确触发条件频繁误触发条件太宽或缺负向描述查看触发日志加限定词和不适用场景触发后立即终止前置条件不满足检查前置条件项补全条件或调整描述执行到一半卡住工具权限不足查看工具调用记录开放对应工具权限6.2 配置报错与权限问题的处理热词里codex is ignoring 1 unrecognized configuration setting和your organization has disabled claude subscription access是两类典型问题。前者是配置字段问题后者是账号权限问题。配置字段问题用“最小配置法”排查把配置精简到最少确认能跑再逐项加回来加到哪项出错就是哪项的问题。权限问题只能从账号层面解决确认订阅状态和组织设置。还有一个常见的是idea设置plugin中插件仓库地址和dsh plugin --profile web add dshmarket这类插件仓库配置问题。如果你在 IDE 里用 skills插件仓库地址要指向正确的源地址写错会导致插件列表加载不出来。这个跟 skill 本身无关但会影响整个使用链路所以也要确认。6.3 skill 执行结果不稳定的应对同样的 skill有时候跑得好有时候跑得差这是最让人头疼的。我的经验是先排除模型因素再排除上下文因素最后看 skill 本身。换一个模型跑同样的 skill如果稳定了说明是模型遵循能力的问题如果换了模型还不稳定看是不是上下文太长导致指令被稀释如果都不是那就是 skill 描述有歧义需要细化。我踩过的一个坑是skill 里用了“适当优化”这种模糊词结果 AI 每次的理解都不一样。后来改成“将重复代码提取为函数函数名以 extract 开头”行为立刻就稳定了。模糊词是稳定性的天敌能删就删能具体就具体。6.4 独家避坑技巧汇总第一个技巧skill 里不要写“如果……则……”的复杂分支AI 在分支判断上容易出错。如果确实需要分支拆成多个 skill用触发条件来区分比在一个 skill 里写 if-else 稳得多。第二个技巧给 skill 加版本号。每次修改后在描述里标注版本这样出问题时能快速定位是哪次改动引入的。我一般用日期加序号比如v20250115-1简单有效。第三个技巧保留一份“最小可用 skill”作为模板。新写 skill 时从模板复制只改触发条件和执行步骤结构不动。这样能避免每次都重新设计结构也降低了格式出错概率。第四个技巧定期清理不再使用的 skill。skill 多了之后加载变慢误触发概率也上升。我每个月会过一遍 skill 列表把三个月没用过的归档或删除。保持精简比堆数量重要。7. 关于 skills 后续可以怎么扩展把单个 skill 跑通之后下一步自然是组合。我现在会把相关的 skill 串成工作流比如“生成组件”之后自动触发“生成测试”测试通过后自动触发“生成变更说明”。这种串联不需要写在一个 skill 里而是通过触发条件让它们自然衔接。热词里agents anywhere和langchain deep agents讨论的多 agent 协作本质上就是这种思路的放大版。另一个方向是给 skill 加“学习能力”。比如记录每次执行的结果如果某类任务经常失败自动调整触发条件或步骤描述。这个我还在试验阶段目前的做法是手动复盘把高频失败点写进 skill 的异常处理里。等积累够多数据再考虑自动化。最后分享一个小技巧如果你在团队里推广 skills不要一上来就要求所有人写。先自己写几个高频场景的 skill跑出效果让大家看到“用了之后确实省事”再逐步推广。强推只会增加抵触用实际收益说话最有效。我自己就是这么做的从一个人用到团队里十几个人用花了大概两个月节奏刚好。