1. 从skills这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是开发者群里skills这个词出现的频率高得离谱。你随便翻一下热搜词列表就能看到claude code skills、codex skills、agent skills测试、skills推荐、skills开发、find skills、superpower skills……一堆词全绕着它转。很多人第一次看到skills这个词脑子里第一反应是技能这跟写代码有什么关系我一开始也是这个反应直到自己真正在 Claude Code 和 Codex 里跑起来几套 skills 之后才明白它到底在干什么。简单说skills 就是给 AI 编程助手agent预置的一套能力包或者操作手册。你可以把它理解成给一个新来的实习生发的员工手册——手册里写清楚了遇到什么情况该怎么做、用哪些工具、遵循什么规范。没有 skills 的 agent就像一个聪明但完全不懂你项目规矩的新人什么都得你现教有了 skills它就能按照你预设的流程和标准去干活输出质量稳定得多。这个内容能做什么它解决的核心问题是让 AI agent 的行为可复用、可约束、可迁移。你写一次 skill之后每次让 agent 处理同类任务它都会按这套规则来不用你反复在 prompt 里啰嗦。适合谁来参考三类人最该看一是已经在用 Claude Code 或 Codex 做日常开发的工程师二是想把团队规范固化到 AI 工作流里的技术负责人三是刚接触 agent 开发、想搞清楚 skills 和普通 prompt 区别的新手。我踩过的坑是一开始我以为 skills 就是写个更长的 prompt结果发现完全不是一回事。prompt 是这一次你这么做skill 是以后遇到这类事你都这么做两者的生命周期、加载机制、触发条件都不一样。下面我把这套东西从设计思路到落地实操完整拆一遍。2. skills 的整体设计与核心思路拆解2.1 为什么需要 skillsprompt 的天花板在哪先说清楚为什么会有 skills 这个东西。你如果只是偶尔用 AI 写几行代码那确实不需要 skills直接对话就够了。但一旦你把 agent 接入到真实项目里问题就来了。第一个问题是上下文漂移。你在对话开头说我们项目用 TypeScript 严格模式所有函数必须写返回类型聊了二十轮之后agent 早就把这事忘了开始给你写any。你每次都得重新提醒烦不胜烦。第二个问题是规范无法沉淀。团队里老张知道我们的 API 层必须做参数校验用 zod但这个知识只存在老张脑子里。他休假了新人用 agent 生成的代码就完全不符合规范。规范没有变成可执行的资产。第三个问题是重复劳动。每次让 agent 做代码审查你都要把审查清单重新贴一遍检查命名、检查错误处理、检查边界条件……这些清单本质上是一样的但每次都要重写。skills 就是冲着这三个问题来的。它把规范和流程从一次性的 prompt 里抽出来变成持久化的、可被 agent 自动加载的能力单元。你写一次之后 agent 在处理相关任务时会自动带上这套规则。2.2 skills 和 prompt、plugin、agent 的关系这几个概念特别容易混我用一张表把它们理清楚概念本质生命周期触发方式典型用途prompt一次性指令单次对话手动输入临时任务skill持久化能力包长期存在自动/手动加载固化规范、复用流程plugin功能扩展模块安装后长期系统级挂载接入外部工具、模型agent执行主体会话级启动即存在实际干活的那个人打个比方agent 是员工plugin 是给他配的电脑和软件skill 是发给他的岗位操作手册prompt 是你临时口头交代的一句话。四者配合起来agent 才能既有能力、又懂规矩、还能被你临时指挥。热搜里出现的plugin、agents、skills经常一起出现就是因为它们在实际使用中是配套的。比如你在 Claude Code 里装一个 plugin 来接入本地模型热搜词里有claude code 调用lmstudio的本地模型然后给这个 agent 配一套 skills 来规范它的输出这就是一套完整的工作流。2.3 skills 的设计原则为什么是文件而不是配置我研究过 Claude Code 和 Codex 里 skills 的组织方式它们有个共同点skills 通常以文件尤其是 Markdown 文件的形式存在而不是塞进某个 JSON 配置里。这个设计选择背后有讲究。第一Markdown 对人类友好。你写 skill 的时候本质上是在写一份给 AI 看的说明书用自然语言描述最直接。如果强制你用结构化配置表达力会大打折扣。第二文件便于版本管理。skill 文件可以进 Git可以 review可以 diff。团队协作时谁改了哪条规范一目了然。这比藏在某个数据库里的配置强太多。第三文件支持渐进式加载。agent 不需要一次性把所有 skill 全读进上下文而是根据当前任务按需加载相关的那几个。这对上下文窗口是极大的节省。提示如果你打算在团队里推广 skills强烈建议把 skill 文件纳入代码仓库统一管理而不是每个人本地各存一份。否则规范会迅速分裂。2.4 一个 skill 的最小结构长什么样虽然不同平台的具体格式有差异但一个 skill 的核心要素是通用的。我总结下来大概是这么几块名称与描述让 agent 知道这个 skill 是干什么的什么时候该用它触发条件什么情况下加载这个 skill比如当用户要求做代码审查时操作步骤具体该怎么做一步步写清楚约束与禁忌哪些事绝对不能做示例给一两个正例和反例帮 agent 理解边界这个结构不是拍脑袋定的它对应的是人类培训新人的逻辑先告诉他这岗位是干嘛的再告诉他什么时候用得上然后教他步骤最后划红线、给样例。你按这个思路写 skillagent 的遵循度会明显更高。3. 核心细节解析与实操要点3.1 skill 的触发机制自动加载 vs 手动调用这是实操中最容易出问题的地方。skills 的触发方式主要有两种自动触发靠的是描述匹配。agent 在接到任务时会拿任务描述去和各个 skill 的描述做语义匹配匹配度高就自动加载。这种方式的好处是省心坏处是可能误触发或者漏触发。我遇到过好几次明明任务很明确agent 却没加载对应的 skill原因就是 skill 的描述写得太模糊。手动调用就是你显式指定用哪个 skill。比如在 Claude Code 里你可以直接说用 xxx skill 来做这件事。这种方式精准但需要你记得有哪些 skill。我的经验是核心规范类 skill 用自动触发专用流程类 skill 用手动调用。比如代码风格规范这种应该自动生效而发布流程这种只在特定时候用的手动调用更合适。3.2 描述字段的写法决定 skill 会不会被用上很多人写 skill 时把精力全花在操作步骤上描述字段随便写两句。这是大错。描述字段决定了 skill 能不能被正确触发它的重要性不亚于正文。我总结了一个描述字段的写法公式[这个 skill 做什么] [在什么场景下使用] [关键触发词]举个例子一个代码审查 skill 的描述差的写法是代码审查相关。好的写法是对 TypeScript 和 React 代码进行静态审查检查类型安全、错误处理、性能隐患。当用户要求 review 代码、检查 PR、或提到代码质量时使用。看出区别了吗好的描述里包含了具体的技术栈、具体的检查项、具体的触发场景和触发词。agent 做语义匹配时这些信息都是加分项。3.3 操作步骤的颗粒度写到什么程度才够这是另一个高频踩坑点。步骤写太粗agent 自由发挥输出不稳定写太细又变成死板的脚本失去灵活性。我的判断标准是写到一个合格的初级工程师看了能照做的程度就够了。具体来说涉及判断的地方给出判断标准而不是直接给结论涉及工具调用的地方写清楚用哪个工具、传什么参数涉及输出的地方给出格式模板涉及取舍的地方说明优先级比如检查错误处理这一条粗的写法是检查错误处理是否完善细的写法是检查每个 async 函数是否有 try-catch 或 .catch检查 catch 块是否至少记录了错误信息检查是否有吞掉错误的情况catch 块为空或只 console.log。后者才是可执行的。3.4 约束与禁忌负向指令怎么写才有效给 AI 写不要做什么比写要做什么更难因为负向指令容易被忽略。我的技巧是把禁忌和后果绑定。比如你写不要使用 any 类型agent 可能还是会用。但如果你写不要使用 any 类型——如果确实需要动态类型用 unknown 配合类型守卫因为 any 会绕过所有类型检查导致运行时错误无法被提前发现遵循度会高很多。原因是后者给了 agent 一个替代方案和理由它知道遇到类似情况该怎么办而不是被简单禁止后无所适从。3.5 示例的写法正例反例都要给示例是 skill 里性价比最高的部分。一个精心设计的示例胜过一大段抽象描述。我的建议是每个关键规则配一组正反例。正例告诉 agent这样做是对的反例告诉它这样做是错的。两者结合边界就清晰了。反例尤其重要因为很多错误是看起来对但其实错的只有明确标出来agent 才能识别。注意示例不要写太长。一个示例控制在 10-20 行代码以内太长会占用大量上下文而且重点不突出。4. 实操过程与核心环节实现4.1 环境准备Claude Code 与 Codex 的安装要点要玩 skills前提是你得先把 agent 环境搭起来。热搜里claude code安装、codex安装、codex安装教程、claude code windows、ubuntu配置claude code这些词高频出现说明安装这一步就卡住了不少人。Claude Code 的安装核心就是 Node 环境加全局包。你需要先确认 Node 版本建议 18 以上然后用 npm 全局安装对应的 CLI 工具。Windows 用户注意某些终端下路径处理会有问题建议用较新的 PowerShell 或者 WSL。Ubuntu 用户相对省心但要注意 npm 全局目录的权限别用 sudo 装全局包容易埋权限坑。Codex 的安装类似也是 CLI 工具。热搜里codex安装 csdn、codex官网下载、codex下载说明大家找安装包找得很辛苦。我的建议是认准官方渠道别从各种第三方站下载版本混乱不说还可能夹带东西。安装完之后第一件事是验证跑一下版本命令确认能正常输出。然后做一次最简单的对话测试确认 agent 能正常响应。这一步别跳过很多后续问题都是安装没装干净导致的。4.2 第一个 skill从零写一个代码审查 skill我拿一个实际例子带你走一遍。假设我们要写一个React 组件代码审查的 skill。第一步确定文件名和位置。不同平台对 skill 存放位置有约定通常在项目根目录下的某个特定文件夹里比如.claude/skills/或类似路径。文件名用有意义的英文比如react-component-review.md。第二步写头部描述。按前面说的公式名称React 组件代码审查 描述对 React 函数组件进行代码审查检查 hooks 使用规范、 性能优化点、可访问性、类型安全。当用户要求审查 React 组件、检查组件代码质量、或提到组件 review 时使用。第三步写操作步骤。我一般分几个检查维度## 检查步骤 1. Hooks 规范检查 - 确认所有 hooks 都在组件顶层调用不在条件或循环里 - 检查 useEffect 依赖数组是否完整 - 检查是否有不必要的 useMemo/useCallback依赖为空或简单值 2. 性能检查 - 检查列表渲染是否有稳定的 key - 检查是否有在渲染中创建新对象/函数导致子组件重渲染 - 检查大计算是否被 useMemo 包裹 3. 可访问性检查 - 交互元素是否有语义化标签 - 图片是否有 alt - 表单控件是否有关联的 label 4. 类型安全检查 - props 是否有明确的类型定义 - 是否有 any 类型 - 事件处理函数的类型是否正确第四步写约束和示例。约束比如不要建议引入新的第三方库除非现有方案确实无法解决。示例给一个正例一个反例。写完这个 skill你下次让 agent 审查 React 组件时它就会按这四个维度来输出结构化的审查报告而不是东一句西一句。4.3 skill 的调试怎么知道它生效了写完 skill 不代表就完事了你得验证它真的被加载、真的被遵循。我的调试方法分三步第一步看加载日志。大多数 agent 工具在加载 skill 时会有日志输出你能看到它加载了哪些 skill。如果该加载的没加载说明描述字段有问题。第二步做对照测试。同一个任务一次带 skill 一次不带对比输出。如果两者没区别说明 skill 没起作用。第三步故意触发边界。给一个 skill 里明确禁止的场景看 agent 会不会踩线。如果踩了说明约束写得不够强。我实测下来最常见的失效原因是描述字段太模糊导致没触发其次是步骤写得太抽象导致 agent 自由发挥。这两个问题占了 skill 失效原因的八成以上。4.4 多 skill 协同避免冲突和覆盖当你有了十几个 skill 之后新问题来了skill 之间可能冲突。比如一个 skill 说优先用函数式写法另一个说优先用类写法agent 就懵了。解决思路有两个。一是分层把 skill 分成全局规范层和任务专用层全局层优先级高任务层在全局层基础上细化。二是明确优先级在 skill 里写清楚当与其他 skill 冲突时以本 skill 为准或者本 skill 是某 skill 的补充。我个人的做法是维护一个 skill 清单文档记录每个 skill 的适用范围和优先级新增 skill 时先检查有没有重叠。这个习惯能省掉大量排查冲突的时间。5. 常见问题与排查技巧实录5.1 skill 不生效的排查清单这是被问得最多的问题。我整理了一张速查表现象可能原因排查方法完全没反应skill 文件位置不对确认存放路径符合平台约定完全没反应文件格式错误检查 Markdown 语法、头部字段偶尔生效描述字段模糊补充具体触发词和场景部分规则被忽略步骤太抽象细化到可执行程度约束被违反负向指令太弱绑定后果和替代方案多个 skill 打架规则冲突检查 skill 间是否有矛盾排查时按这个顺序来先确认加载再确认触发最后确认遵循。别一上来就改内容很多时候问题出在加载环节。5.2 上下文被 skill 撑爆怎么办skill 写多了全加载进上下文窗口就不够用了。这是规模化使用 skills 后的必然问题。我的应对策略是分级加载。把 skill 分成三类常驻类每次都要用的核心规范、按需类特定任务才用的、归档类很少用但不想删的。常驻类保持精简按需类靠描述匹配触发归档类平时不加载。另外skill 本身也要精简。我见过有人一个 skill 写了两千字里面一半是废话。skill 不是文档不需要面面俱到抓住关键规则和易错点就行。5.3 团队协作中 skill 的版本管理团队用 skills最大的坑是版本不一致。张三改了 skill李四本地还是旧的两人用 agent 生成的代码风格就不一样。解决办法就是把 skill 目录纳入 Git 管理改 skill 走正常的 PR 流程。同时约定一个规则skill 的修改要在 commit message 里说明改了什么、为什么改。这样出问题时能追溯。还有个细节skill 里如果引用了项目特定的路径、命令、配置要确保这些在团队所有成员的环境里都成立。我踩过一次坑skill 里写死了一个只有我本地才有的脚本路径结果同事用了直接报错。5.4 从热搜问题看典型故障热搜里有些词其实反映了真实的故障场景。比如cc switch local proxy failed while handling codex endpoint /responses这类本质是网络配置或端点配置的问题跟 skill 本身无关但会让人误以为是 skill 失效。排查时要先分清是环境问题还是skill 问题。再比如your organization has disabled claude subscription access这种是账号权限层面的限制也不是 skill 能解决的。遇到这类先确认基础环境正常再怀疑 skill。还有qt.qpa.plugin: could not find the qt platform plugin这种是依赖库缺失属于环境问题。我的经验是任何skill 不生效的报错先跑一个不带 skill 的基础任务如果基础任务也失败那就是环境问题跟 skill 无关。这个判断能帮你省掉大量无效排查。5.5 几个我踩过的真实坑第一个坑skill 描述里用了太多同义词。我以为多写几个同义词能提高触发率结果反而稀释了匹配精度该触发的时候没触发。后来改成精准描述效果好多了。第二个坑在 skill 里写了互相矛盾的规则。前面说优先性能后面说优先可读性agent 无所适从。后来我加了优先级说明才解决。第三个坑skill 更新后没重启 agent。有些平台会缓存 skill改了文件不重启不生效。这个坑我踩了不止一次现在改完 skill 第一件事就是重启验证。第四个坑把 skill 当文档写。写了一堆背景介绍、原理说明真正可执行的规则没几条。后来我定了个规矩skill 里每一段都要能对应到一个具体动作或判断否则删掉。6. skills 的进阶玩法与扩展方向6.1 把 skill 和 plugin 组合起来用单用 skill 是告诉 agent 怎么做单用 plugin 是给 agent 加能力。两者组合威力更大。比如你装一个能访问数据库的 plugin再配一个数据库查询规范的 skillagent 就能既连得上数据库、又按规范查询。热搜里dsh plugin --profile web add dshmarket、idea设置plugin中插件仓库地址这些词说明大家已经在折腾 plugin 了。我的建议是先想清楚要解决什么问题再决定用 plugin 还是 skill。需要外部能力的用 plugin需要规范行为的用 skill。6.2 skill 的测试与质量保障skill 也是代码也该有测试。我现在的做法是给每个核心 skill 配一组测试用例输入什么任务、期望 agent 输出什么、实际输出什么。跑一遍就知道 skill 有没有退化。这个做法在 skill 数量多了之后尤其重要。你改了一个 skill可能影响到依赖它的其他 skill有测试就能快速发现回归。6.3 从个人用到团队资产skills 最大的价值在于把个人经验变成团队资产。一个资深工程师脑子里的规范写成 skill 之后团队里每个人用 agent 都能享受到。我推动团队用 skills 的顺序是这样的先自己用跑通几个核心场景然后挑出最通用的两三个 skill 在小组内推广最后形成团队级的 skill 库。这个过程别急一上来就搞大而全的 skill 库往往没人用。6.4 后续可以怎么扩展skills 这套东西还在快速演进。我观察到几个方向值得关注一是 skill 的自动生成让 agent 从历史对话里总结出可复用的 skill二是 skill 的市场化热搜里claude 国内安装skills 官方市场、find skills、skills推荐这些词说明已经有 skill 分享和分发的需求了三是 skill 和 agent 编排的结合多个 agent 各带各的 skill 协同干活。我个人的体会是skills 这东西的价值不在多而在精。与其写二十个半吊子 skill不如把三五个核心 skill 打磨到位。我现在维护的 skill 不超过十个但每一个都是反复迭代过的用起来很稳。最后分享一个小技巧每次 agent 输出不符合预期时别急着改 prompt先想想是不是该更新对应的 skill——把这次的教训固化进去下次就不会再犯。这个习惯坚持下来你的 skill 库会越来越值钱。
1. 从skills这个热词说起它到底在解决什么问题最近半年不管是在技术社区还是开发者群里skills这个词出现的频率高得离谱。你随便翻一下热搜词列表就能看到claude code skills、codex skills、agent skills测试、skills推荐、skills开发、find skills、superpower skills……一堆词全绕着它转。很多人第一次看到skills这个词脑子里第一反应是技能这跟写代码有什么关系我一开始也是这个反应直到自己真正在 Claude Code 和 Codex 里跑起来几套 skills 之后才明白它到底在干什么。简单说skills 就是给 AI 编程助手agent预置的一套能力包或者操作手册。你可以把它理解成给一个新来的实习生发的员工手册——手册里写清楚了遇到什么情况该怎么做、用哪些工具、遵循什么规范。没有 skills 的 agent就像一个聪明但完全不懂你项目规矩的新人什么都得你现教有了 skills它就能按照你预设的流程和标准去干活输出质量稳定得多。这个内容能做什么它解决的核心问题是让 AI agent 的行为可复用、可约束、可迁移。你写一次 skill之后每次让 agent 处理同类任务它都会按这套规则来不用你反复在 prompt 里啰嗦。适合谁来参考三类人最该看一是已经在用 Claude Code 或 Codex 做日常开发的工程师二是想把团队规范固化到 AI 工作流里的技术负责人三是刚接触 agent 开发、想搞清楚 skills 和普通 prompt 区别的新手。我踩过的坑是一开始我以为 skills 就是写个更长的 prompt结果发现完全不是一回事。prompt 是这一次你这么做skill 是以后遇到这类事你都这么做两者的生命周期、加载机制、触发条件都不一样。下面我把这套东西从设计思路到落地实操完整拆一遍。2. skills 的整体设计与核心思路拆解2.1 为什么需要 skillsprompt 的天花板在哪先说清楚为什么会有 skills 这个东西。你如果只是偶尔用 AI 写几行代码那确实不需要 skills直接对话就够了。但一旦你把 agent 接入到真实项目里问题就来了。第一个问题是上下文漂移。你在对话开头说我们项目用 TypeScript 严格模式所有函数必须写返回类型聊了二十轮之后agent 早就把这事忘了开始给你写any。你每次都得重新提醒烦不胜烦。第二个问题是规范无法沉淀。团队里老张知道我们的 API 层必须做参数校验用 zod但这个知识只存在老张脑子里。他休假了新人用 agent 生成的代码就完全不符合规范。规范没有变成可执行的资产。第三个问题是重复劳动。每次让 agent 做代码审查你都要把审查清单重新贴一遍检查命名、检查错误处理、检查边界条件……这些清单本质上是一样的但每次都要重写。skills 就是冲着这三个问题来的。它把规范和流程从一次性的 prompt 里抽出来变成持久化的、可被 agent 自动加载的能力单元。你写一次之后 agent 在处理相关任务时会自动带上这套规则。2.2 skills 和 prompt、plugin、agent 的关系这几个概念特别容易混我用一张表把它们理清楚概念本质生命周期触发方式典型用途prompt一次性指令单次对话手动输入临时任务skill持久化能力包长期存在自动/手动加载固化规范、复用流程plugin功能扩展模块安装后长期系统级挂载接入外部工具、模型agent执行主体会话级启动即存在实际干活的那个人打个比方agent 是员工plugin 是给他配的电脑和软件skill 是发给他的岗位操作手册prompt 是你临时口头交代的一句话。四者配合起来agent 才能既有能力、又懂规矩、还能被你临时指挥。热搜里出现的plugin、agents、skills经常一起出现就是因为它们在实际使用中是配套的。比如你在 Claude Code 里装一个 plugin 来接入本地模型热搜词里有claude code 调用lmstudio的本地模型然后给这个 agent 配一套 skills 来规范它的输出这就是一套完整的工作流。2.3 skills 的设计原则为什么是文件而不是配置我研究过 Claude Code 和 Codex 里 skills 的组织方式它们有个共同点skills 通常以文件尤其是 Markdown 文件的形式存在而不是塞进某个 JSON 配置里。这个设计选择背后有讲究。第一Markdown 对人类友好。你写 skill 的时候本质上是在写一份给 AI 看的说明书用自然语言描述最直接。如果强制你用结构化配置表达力会大打折扣。第二文件便于版本管理。skill 文件可以进 Git可以 review可以 diff。团队协作时谁改了哪条规范一目了然。这比藏在某个数据库里的配置强太多。第三文件支持渐进式加载。agent 不需要一次性把所有 skill 全读进上下文而是根据当前任务按需加载相关的那几个。这对上下文窗口是极大的节省。提示如果你打算在团队里推广 skills强烈建议把 skill 文件纳入代码仓库统一管理而不是每个人本地各存一份。否则规范会迅速分裂。2.4 一个 skill 的最小结构长什么样虽然不同平台的具体格式有差异但一个 skill 的核心要素是通用的。我总结下来大概是这么几块名称与描述让 agent 知道这个 skill 是干什么的什么时候该用它触发条件什么情况下加载这个 skill比如当用户要求做代码审查时操作步骤具体该怎么做一步步写清楚约束与禁忌哪些事绝对不能做示例给一两个正例和反例帮 agent 理解边界这个结构不是拍脑袋定的它对应的是人类培训新人的逻辑先告诉他这岗位是干嘛的再告诉他什么时候用得上然后教他步骤最后划红线、给样例。你按这个思路写 skillagent 的遵循度会明显更高。3. 核心细节解析与实操要点3.1 skill 的触发机制自动加载 vs 手动调用这是实操中最容易出问题的地方。skills 的触发方式主要有两种自动触发靠的是描述匹配。agent 在接到任务时会拿任务描述去和各个 skill 的描述做语义匹配匹配度高就自动加载。这种方式的好处是省心坏处是可能误触发或者漏触发。我遇到过好几次明明任务很明确agent 却没加载对应的 skill原因就是 skill 的描述写得太模糊。手动调用就是你显式指定用哪个 skill。比如在 Claude Code 里你可以直接说用 xxx skill 来做这件事。这种方式精准但需要你记得有哪些 skill。我的经验是核心规范类 skill 用自动触发专用流程类 skill 用手动调用。比如代码风格规范这种应该自动生效而发布流程这种只在特定时候用的手动调用更合适。3.2 描述字段的写法决定 skill 会不会被用上很多人写 skill 时把精力全花在操作步骤上描述字段随便写两句。这是大错。描述字段决定了 skill 能不能被正确触发它的重要性不亚于正文。我总结了一个描述字段的写法公式[这个 skill 做什么] [在什么场景下使用] [关键触发词]举个例子一个代码审查 skill 的描述差的写法是代码审查相关。好的写法是对 TypeScript 和 React 代码进行静态审查检查类型安全、错误处理、性能隐患。当用户要求 review 代码、检查 PR、或提到代码质量时使用。看出区别了吗好的描述里包含了具体的技术栈、具体的检查项、具体的触发场景和触发词。agent 做语义匹配时这些信息都是加分项。3.3 操作步骤的颗粒度写到什么程度才够这是另一个高频踩坑点。步骤写太粗agent 自由发挥输出不稳定写太细又变成死板的脚本失去灵活性。我的判断标准是写到一个合格的初级工程师看了能照做的程度就够了。具体来说涉及判断的地方给出判断标准而不是直接给结论涉及工具调用的地方写清楚用哪个工具、传什么参数涉及输出的地方给出格式模板涉及取舍的地方说明优先级比如检查错误处理这一条粗的写法是检查错误处理是否完善细的写法是检查每个 async 函数是否有 try-catch 或 .catch检查 catch 块是否至少记录了错误信息检查是否有吞掉错误的情况catch 块为空或只 console.log。后者才是可执行的。3.4 约束与禁忌负向指令怎么写才有效给 AI 写不要做什么比写要做什么更难因为负向指令容易被忽略。我的技巧是把禁忌和后果绑定。比如你写不要使用 any 类型agent 可能还是会用。但如果你写不要使用 any 类型——如果确实需要动态类型用 unknown 配合类型守卫因为 any 会绕过所有类型检查导致运行时错误无法被提前发现遵循度会高很多。原因是后者给了 agent 一个替代方案和理由它知道遇到类似情况该怎么办而不是被简单禁止后无所适从。3.5 示例的写法正例反例都要给示例是 skill 里性价比最高的部分。一个精心设计的示例胜过一大段抽象描述。我的建议是每个关键规则配一组正反例。正例告诉 agent这样做是对的反例告诉它这样做是错的。两者结合边界就清晰了。反例尤其重要因为很多错误是看起来对但其实错的只有明确标出来agent 才能识别。注意示例不要写太长。一个示例控制在 10-20 行代码以内太长会占用大量上下文而且重点不突出。4. 实操过程与核心环节实现4.1 环境准备Claude Code 与 Codex 的安装要点要玩 skills前提是你得先把 agent 环境搭起来。热搜里claude code安装、codex安装、codex安装教程、claude code windows、ubuntu配置claude code这些词高频出现说明安装这一步就卡住了不少人。Claude Code 的安装核心就是 Node 环境加全局包。你需要先确认 Node 版本建议 18 以上然后用 npm 全局安装对应的 CLI 工具。Windows 用户注意某些终端下路径处理会有问题建议用较新的 PowerShell 或者 WSL。Ubuntu 用户相对省心但要注意 npm 全局目录的权限别用 sudo 装全局包容易埋权限坑。Codex 的安装类似也是 CLI 工具。热搜里codex安装 csdn、codex官网下载、codex下载说明大家找安装包找得很辛苦。我的建议是认准官方渠道别从各种第三方站下载版本混乱不说还可能夹带东西。安装完之后第一件事是验证跑一下版本命令确认能正常输出。然后做一次最简单的对话测试确认 agent 能正常响应。这一步别跳过很多后续问题都是安装没装干净导致的。4.2 第一个 skill从零写一个代码审查 skill我拿一个实际例子带你走一遍。假设我们要写一个React 组件代码审查的 skill。第一步确定文件名和位置。不同平台对 skill 存放位置有约定通常在项目根目录下的某个特定文件夹里比如.claude/skills/或类似路径。文件名用有意义的英文比如react-component-review.md。第二步写头部描述。按前面说的公式名称React 组件代码审查 描述对 React 函数组件进行代码审查检查 hooks 使用规范、 性能优化点、可访问性、类型安全。当用户要求审查 React 组件、检查组件代码质量、或提到组件 review 时使用。第三步写操作步骤。我一般分几个检查维度## 检查步骤 1. Hooks 规范检查 - 确认所有 hooks 都在组件顶层调用不在条件或循环里 - 检查 useEffect 依赖数组是否完整 - 检查是否有不必要的 useMemo/useCallback依赖为空或简单值 2. 性能检查 - 检查列表渲染是否有稳定的 key - 检查是否有在渲染中创建新对象/函数导致子组件重渲染 - 检查大计算是否被 useMemo 包裹 3. 可访问性检查 - 交互元素是否有语义化标签 - 图片是否有 alt - 表单控件是否有关联的 label 4. 类型安全检查 - props 是否有明确的类型定义 - 是否有 any 类型 - 事件处理函数的类型是否正确第四步写约束和示例。约束比如不要建议引入新的第三方库除非现有方案确实无法解决。示例给一个正例一个反例。写完这个 skill你下次让 agent 审查 React 组件时它就会按这四个维度来输出结构化的审查报告而不是东一句西一句。4.3 skill 的调试怎么知道它生效了写完 skill 不代表就完事了你得验证它真的被加载、真的被遵循。我的调试方法分三步第一步看加载日志。大多数 agent 工具在加载 skill 时会有日志输出你能看到它加载了哪些 skill。如果该加载的没加载说明描述字段有问题。第二步做对照测试。同一个任务一次带 skill 一次不带对比输出。如果两者没区别说明 skill 没起作用。第三步故意触发边界。给一个 skill 里明确禁止的场景看 agent 会不会踩线。如果踩了说明约束写得不够强。我实测下来最常见的失效原因是描述字段太模糊导致没触发其次是步骤写得太抽象导致 agent 自由发挥。这两个问题占了 skill 失效原因的八成以上。4.4 多 skill 协同避免冲突和覆盖当你有了十几个 skill 之后新问题来了skill 之间可能冲突。比如一个 skill 说优先用函数式写法另一个说优先用类写法agent 就懵了。解决思路有两个。一是分层把 skill 分成全局规范层和任务专用层全局层优先级高任务层在全局层基础上细化。二是明确优先级在 skill 里写清楚当与其他 skill 冲突时以本 skill 为准或者本 skill 是某 skill 的补充。我个人的做法是维护一个 skill 清单文档记录每个 skill 的适用范围和优先级新增 skill 时先检查有没有重叠。这个习惯能省掉大量排查冲突的时间。5. 常见问题与排查技巧实录5.1 skill 不生效的排查清单这是被问得最多的问题。我整理了一张速查表现象可能原因排查方法完全没反应skill 文件位置不对确认存放路径符合平台约定完全没反应文件格式错误检查 Markdown 语法、头部字段偶尔生效描述字段模糊补充具体触发词和场景部分规则被忽略步骤太抽象细化到可执行程度约束被违反负向指令太弱绑定后果和替代方案多个 skill 打架规则冲突检查 skill 间是否有矛盾排查时按这个顺序来先确认加载再确认触发最后确认遵循。别一上来就改内容很多时候问题出在加载环节。5.2 上下文被 skill 撑爆怎么办skill 写多了全加载进上下文窗口就不够用了。这是规模化使用 skills 后的必然问题。我的应对策略是分级加载。把 skill 分成三类常驻类每次都要用的核心规范、按需类特定任务才用的、归档类很少用但不想删的。常驻类保持精简按需类靠描述匹配触发归档类平时不加载。另外skill 本身也要精简。我见过有人一个 skill 写了两千字里面一半是废话。skill 不是文档不需要面面俱到抓住关键规则和易错点就行。5.3 团队协作中 skill 的版本管理团队用 skills最大的坑是版本不一致。张三改了 skill李四本地还是旧的两人用 agent 生成的代码风格就不一样。解决办法就是把 skill 目录纳入 Git 管理改 skill 走正常的 PR 流程。同时约定一个规则skill 的修改要在 commit message 里说明改了什么、为什么改。这样出问题时能追溯。还有个细节skill 里如果引用了项目特定的路径、命令、配置要确保这些在团队所有成员的环境里都成立。我踩过一次坑skill 里写死了一个只有我本地才有的脚本路径结果同事用了直接报错。5.4 从热搜问题看典型故障热搜里有些词其实反映了真实的故障场景。比如cc switch local proxy failed while handling codex endpoint /responses这类本质是网络配置或端点配置的问题跟 skill 本身无关但会让人误以为是 skill 失效。排查时要先分清是环境问题还是skill 问题。再比如your organization has disabled claude subscription access这种是账号权限层面的限制也不是 skill 能解决的。遇到这类先确认基础环境正常再怀疑 skill。还有qt.qpa.plugin: could not find the qt platform plugin这种是依赖库缺失属于环境问题。我的经验是任何skill 不生效的报错先跑一个不带 skill 的基础任务如果基础任务也失败那就是环境问题跟 skill 无关。这个判断能帮你省掉大量无效排查。5.5 几个我踩过的真实坑第一个坑skill 描述里用了太多同义词。我以为多写几个同义词能提高触发率结果反而稀释了匹配精度该触发的时候没触发。后来改成精准描述效果好多了。第二个坑在 skill 里写了互相矛盾的规则。前面说优先性能后面说优先可读性agent 无所适从。后来我加了优先级说明才解决。第三个坑skill 更新后没重启 agent。有些平台会缓存 skill改了文件不重启不生效。这个坑我踩了不止一次现在改完 skill 第一件事就是重启验证。第四个坑把 skill 当文档写。写了一堆背景介绍、原理说明真正可执行的规则没几条。后来我定了个规矩skill 里每一段都要能对应到一个具体动作或判断否则删掉。6. skills 的进阶玩法与扩展方向6.1 把 skill 和 plugin 组合起来用单用 skill 是告诉 agent 怎么做单用 plugin 是给 agent 加能力。两者组合威力更大。比如你装一个能访问数据库的 plugin再配一个数据库查询规范的 skillagent 就能既连得上数据库、又按规范查询。热搜里dsh plugin --profile web add dshmarket、idea设置plugin中插件仓库地址这些词说明大家已经在折腾 plugin 了。我的建议是先想清楚要解决什么问题再决定用 plugin 还是 skill。需要外部能力的用 plugin需要规范行为的用 skill。6.2 skill 的测试与质量保障skill 也是代码也该有测试。我现在的做法是给每个核心 skill 配一组测试用例输入什么任务、期望 agent 输出什么、实际输出什么。跑一遍就知道 skill 有没有退化。这个做法在 skill 数量多了之后尤其重要。你改了一个 skill可能影响到依赖它的其他 skill有测试就能快速发现回归。6.3 从个人用到团队资产skills 最大的价值在于把个人经验变成团队资产。一个资深工程师脑子里的规范写成 skill 之后团队里每个人用 agent 都能享受到。我推动团队用 skills 的顺序是这样的先自己用跑通几个核心场景然后挑出最通用的两三个 skill 在小组内推广最后形成团队级的 skill 库。这个过程别急一上来就搞大而全的 skill 库往往没人用。6.4 后续可以怎么扩展skills 这套东西还在快速演进。我观察到几个方向值得关注一是 skill 的自动生成让 agent 从历史对话里总结出可复用的 skill二是 skill 的市场化热搜里claude 国内安装skills 官方市场、find skills、skills推荐这些词说明已经有 skill 分享和分发的需求了三是 skill 和 agent 编排的结合多个 agent 各带各的 skill 协同干活。我个人的体会是skills 这东西的价值不在多而在精。与其写二十个半吊子 skill不如把三五个核心 skill 打磨到位。我现在维护的 skill 不超过十个但每一个都是反复迭代过的用起来很稳。最后分享一个小技巧每次 agent 输出不符合预期时别急着改 prompt先想想是不是该更新对应的 skill——把这次的教训固化进去下次就不会再犯。这个习惯坚持下来你的 skill 库会越来越值钱。
