1. 从skills这个模糊词说起它到底指什么第一次看到skills这个词被单独拎出来当项目标题我其实愣了一下。这个词太泛了泛到像在搜索引擎里敲工具两个字。但结合热搜词里反复出现的 Claude Code、Codex、plugin、agents 这些词方向就清晰了——这里说的 skills指的是围绕 AI 编程助手尤其是 Claude Code 和 Codex 这类命令行 Agent 工具构建的能力扩展单元。打个比方。Claude Code 或者 Codex 本身像是一个刚入职的聪明实习生脑子好使、学东西快但它不知道你们团队的具体规矩代码提交前要跑哪几个检查、日志格式长什么样、某个内部 API 怎么调。skills 就是给这个实习生发的岗位操作手册——一份份写清楚遇到这类任务按这个流程、用这些工具、产出这种格式的说明文件。它可以是纯提示词也可以捆绑脚本、模板、参考文档。为什么这个东西突然火了因为大家发现光靠一个通用大模型写代码产出质量飘忽不定。同一个需求今天写得漂亮明天就给你埋个坑。而 skills 的价值在于把某类任务怎么做才对这件事固化下来让 Agent 每次执行都有章可循。这跟传统开发里把重复逻辑抽成函数是一个思路只不过抽出来的不是代码是工作方法和领域知识。这篇内容适合谁看三类人一是刚装上 Claude Code 或 Codex、还在摸索怎么让它听话的新手二是已经用了一阵、但每次都要重复交代背景、想提升效率的老用户三是想自己动手写 skills、把团队经验沉淀下来的开发者。我会从概念讲到实操再到自己踩过的坑尽量把这件事说透。需要先明确一点skills 不是某个官方统一标准不同工具对它的叫法、加载方式、文件结构都有差异。Claude Code 里叫 Agent SkillsCodex 里也有类似机制社区里还有各种第三方 skills 市场。所以下面讲的时候我会尽量区分场景避免你把 A 工具的写法直接套到 B 工具上。2. 拆开一个 skill 看内部它凭什么能让 Agent 变聪明2.1 skill 的最小构成一个入口文件加若干资源一个能用的 skill核心通常是一个 Markdown 文件常见命名是SKILL.md或类似里面用自然语言描述这个 skill 是干什么的、什么时候触发、执行步骤是什么。旁边可以挂脚本、模板、示例数据。Agent 在运行时会根据当前任务判断要不要加载某个 skill加载后就把里面的内容当作额外上下文来指导自己的行为。这个机制听起来简单但威力在于按需加载。你不可能把所有领域知识一股脑塞进系统提示词里那样既占上下文又互相干扰。skills 的思路是用到哪个加载哪个就像你查手册时只翻相关那一章而不是把整本书背下来。我见过不少人把 skill 写成一大段空泛的你要认真思考、要保证质量这种基本没用。有效的 skill 一定是具体到可执行的输入是什么、输出格式是什么、中间要调用哪些命令、遇到什么情况该停下来问人。判断标准很简单——换一个完全不了解背景的人或 Agent照着做能不能得到稳定结果。2.2 触发机制Agent 怎么知道该用哪个 skill这是很多人困惑的点。skill 写好了Agent 怎么知道什么时候该调用它目前主流做法有两种。一种是描述匹配。skill 文件头部会有一段简短的 description说明适用场景。Agent 拿到用户请求后会拿请求去和各个 skill 的描述做语义匹配匹配度高就加载。这就要求 description 写得精准既不能太窄覆盖不到该用的场景也不能太宽到处乱触发。另一种是显式调用。用户在对话里直接点名比如用 XX skill 来处理这个任务。这种方式最可靠适合你已经明确知道该用哪个 skill 的场景。实测下来最稳的组合是description 写清楚边界日常靠自动匹配关键任务手动点名兜底。我自己的习惯是凡是涉及固定流程的任务比如生成周报、格式化日志、跑某套检查一律手动点名避免 Agent 自作主张用错工具。2.3 为什么知识固化比反复交代更划算算一笔账。假设你每天要让 Agent 做 5 次某类任务每次交代背景要花 200 字一天就是 1000 字的重复输入。一个月下来是 3 万字。这还只是输入成本更贵的是不确定性——你每次交代的措辞略有不同Agent 的理解就可能跑偏产出质量不稳定你还得反复纠正。把这些固化成一个 skill前期投入可能是一两个小时但之后每次调用只需要一句话。更重要的是产出变得可预期。对于团队协作场景skill 还能当作文档新人无论是人还是 Agent照着做就能对齐标准。这也是为什么热搜里skills 开发skills 推荐这类词热度高——大家已经过了尝鲜期开始认真考虑怎么把这件事工程化。3. 上手实操从零写一个能用的 skill3.1 先想清楚边界再动手写新手最容易犯的错是上来就写内容。正确顺序是先回答三个问题这个 skill 解决什么任务输入是什么输出长什么样举个例子我想做一个代码审查报告生成的 skill。任务边界是给定一个代码 diff产出一份结构化的审查意见。输入是 diff 文本或文件路径。输出是固定格式的 Markdown包含问题清单、严重程度、修改建议三部分。边界定清楚后写内容就是填空。我见过有人把 skill 写成帮我审查代码这种等于没写因为 Agent 本来就会审查代码你只是重复了一遍它的默认能力。skill 的增量价值在于约束和规范——规定它必须按你的格式、你的检查项、你的优先级来输出。3.2 文件结构一个可复用的模板下面是我常用的 skill 目录结构你可以直接抄my-skill/ SKILL.md # 入口描述和主流程 templates/ # 输出模板 report.md scripts/ # 辅助脚本 check.sh examples/ # 输入输出示例 input.txt output.mdSKILL.md是核心其余都是可选资源。入口文件我一般这么组织--- name: code-review-report description: 当用户提供代码 diff 并需要结构化审查报告时使用。不适用于单行代码问答。 --- ## 任务 根据输入的代码 diff生成结构化审查报告。 ## 步骤 1. 读取 diff 内容识别改动涉及的文件和函数 2. 按检查项逐条审查空指针、边界条件、错误处理、命名规范 3. 按模板 templates/report.md 输出 ## 输出要求 - 问题按严重程度排序阻断 严重 建议 - 每条问题必须给出具体行号和修改建议 - 无问题时明确写未发现问题不要编造注意 description 里那句不适用于单行代码问答这是负向边界能有效减少误触发。很多人只写正向描述结果 Agent 什么鸡毛蒜皮都往里套。3.3 把流程写成可执行步骤而不是原则对比两种写法。写法 A请仔细审查代码注意潜在问题。写法 B逐行检查是否存在数组越界、空指针解引用、未处理的异常分支对每个函数确认入参校验。写法 A 是原则Agent 看了等于没看。写法 B 是步骤Agent 可以逐条执行、逐条汇报。skill 的质量很大程度上取决于你把多少隐性经验翻译成了显性步骤。这里有个技巧写步骤时想象你在带一个刚毕业的实习生。他不会读心术你得告诉他先做什么、再做什么、做到什么程度算完成。凡是你懂的按惯例这种词都要替换成具体动作。3.4 用示例锚定输出格式光描述格式不够最好给一两个输入输出示例。Agent 对示例的模仿能力很强一个具体的例子胜过三段抽象描述。我的做法是在examples/里放一对真实的输入输出。比如输入是一段有问题的 diff输出是完整的审查报告。Agent 加载 skill 时如果读到这个示例产出的格式会高度贴近。这比你在描述里写输出要专业、要清晰有用一百倍。提示示例不要放太复杂的选一个能覆盖主要格式特征的简单案例即可。太复杂的示例反而会让 Agent 抓不住重点。4. 装好之后怎么用Claude Code 与 Codex 的差异4.1 Claude Code 里的 skills 加载位置Claude Code 对 skills 的支持相对成熟。通常你把 skill 目录放到约定的位置比如项目根目录下的特定文件夹或用户级配置目录它就能被识别。具体路径各版本可能有调整建议以你当前版本的文档为准。我自己的习惯是项目级 skill 和用户级 skill 分开。项目级的放项目里跟着代码走团队共享用户级的放个人配置目录处理跨项目的通用任务。这样切换项目时不会互相污染。一个容易忽略的点Claude Code 加载 skill 是有上下文成本的。skill 越多匹配时的干扰越大。所以不要贪多把不用的及时清理。我一般控制在同时启用 5 到 8 个超过就考虑合并或归档。4.2 Codex 场景下的对应机制Codex 这边的机制和 Claude Code 不完全一样但思路相通——都是通过某种配置让 Agent 获得额外的领域指令。热搜里codex skillscodex 好用的 skills说明已经有不少人在这个方向折腾。在 Codex 里我更多是把 skill 当作任务模板来用。因为 Codex 的执行链路和 Claude Code 有差异直接照搬 skill 文件不一定生效。我的做法是把核心流程抽出来适配成 Codex 能理解的指令格式必要时配合脚本。这里要提醒一句不要假设两个工具的 skill 可以无缝互转。它们的触发逻辑、上下文注入方式、对文件结构的期望都可能不同。跨工具复用时一定要重新测试触发是否正常、输出是否符合预期。4.3 本地模型接入时的注意事项热搜里有个词是claude code 调用 lmstudio 的本地模型。这个场景下用 skills 要额外小心。本地模型的能力参差不齐对复杂 skill 的理解和遵循程度可能不如云端大模型。我的经验是接本地模型时skill 要写得更短、更直白步骤要更少。复杂的多分支流程本地模型很容易执行到一半就跑偏。可以先把 skill 拆成几个小单元逐个验证本地模型能不能稳定执行再考虑组合。另外本地模型的上下文窗口通常更紧张skill 里挂太多参考文档会挤占空间。这时候按需加载的设计就更重要了——只加载当前任务真正需要的那部分。5. 踩过的坑那些文档里不会写的教训5.1 描述写太宽Agent 到处乱触发我最早写的一个 skilldescription 写的是处理各种文档相关任务。结果那段时间 Agent 干什么都想调用它连写代码注释都要套进来输出一堆不相关的内容。后来把描述收窄到仅用于将 Markdown 转换为特定格式的 PDF 报告误触发立刻消失。教训很直接description 的边界要窄到有点小气。宁可漏触发大不了手动点名也不要乱触发。乱触发的代价是污染整个对话的上下文后面很难纠正回来。5.2 步骤里藏了隐含前提有次我写了个 skill步骤里有一句参考项目现有的日志规范。我以为 Agent 会自己去翻代码找规范结果它压根没找直接按通用格式输出了。问题出在参考现有规范是个隐含前提——它假设 Agent 知道规范在哪、长什么样。修正方法把隐含前提显式化。改成读取docs/logging.md按其定义的字段顺序输出日志。明确到文件路径Agent 才知道去哪找。凡是涉及项目约定团队规范这类词都要落到具体文件或具体规则上。5.3 输出格式没约束每次都不一样早期我偷懒skill 里只写输出一份报告没规定格式。结果每次产出的结构都不同有时是列表有时是表格有时是散文。后来加了模板文件并在步骤里明确严格按 templates/report.md 的结构输出稳定性立刻上来了。这件事让我意识到Agent 的默认行为是合理发挥而 skill 的作用是限制发挥。你约束得越具体产出越稳定。想要创意的时候放开想要稳定的时候收紧这是两个不同的使用场景。5.4 版本更新后 skill 失效工具本身在快速迭代某次更新后我发现之前能正常触发的 skill 不灵了。排查下来是加载路径或描述匹配逻辑变了。这类问题没有通用解法只能养成习惯工具升级后抽时间回归测试一下常用 skill。我的做法是维护一个冒烟测试清单每个 skill 配一句最简单的触发指令。升级后挨个跑一遍确认还能正常工作。花不了几分钟但能避免关键时刻掉链子。6. 进阶玩法把 skills 变成团队资产6.1 用 skill 沉淀只有老员工知道的经验每个团队都有一些口口相传的隐性知识某个接口有坑、某类改动必须同步更新文档、某个环境的配置有特殊要求。这些以前靠带教传递现在可以写成 skill。比如发布前检查这个 skill把发布流程里所有容易漏的步骤固化下来更新版本号、同步 changelog、跑回归测试、通知相关方。Agent 执行时逐条核对比人肉记忆可靠得多。这类 skill 的价值随时间增长——写得越多团队整体的执行一致性越高。6.2 skill 的版本管理与评审既然 skill 是资产就该像代码一样管理。我的做法是把 skill 放进 Git 仓库改动走评审流程。评审重点看三件事描述边界是否清晰、步骤是否可执行、输出是否有明确约束。这样做还有个好处skill 的演进历史可追溯。某次产出出问题时可以回看是不是最近改了某个 skill 导致的。没有版本管理的话这种排查基本靠猜。6.3 组合多个 skill 完成复杂任务单个 skill 解决单点问题复杂任务可以串起来。比如生成周报这个任务可以拆成收集本周提交记录汇总任务进展按模板生成报告三个 skill依次调用。不过要注意skill 串联时上下文会累积容易超出窗口或互相干扰。我的经验是每个 skill 的输出尽量精简只保留下游需要的信息中间过程该丢就丢。串联数量也别太多超过三四个就该考虑合并成一个更大的 skill或者用脚本在中间做数据转换。6.4 什么时候不该用 skill不是所有事都值得写成 skill。判断标准这件事是否高频、是否有固定流程、是否容易出错。三个都满足值得写只满足一个可能没必要。低频的一次性任务写 skill 的时间比直接做还长。没有固定流程的探索性任务skill 反而会限制发挥。不容易出错的简单任务写了也是浪费上下文。我见过有人给重命名变量这种操作写 skill纯属过度工程。7. 关于 skills 生态的一些观察热搜里skills 推荐find skillsskills 官方市场这些词说明社区已经在往共享 skill的方向走。有人写好 skill 发布出来别人直接拿来用。这个趋势是好事能减少重复造轮子。但用别人的 skill 要留个心眼。一是适配性别人的 skill 是基于他的项目结构和工具版本写的直接拿来可能水土不服。二是安全性skill 里可能包含脚本或外部调用来源不明的要审一遍再用。三是可维护性依赖别人的 skill对方不更新了你也没辙关键流程最好自己掌握。我的策略是通用型 skill比如格式化、转换类可以用社区的省事涉及核心业务流程的一律自己写、自己维护。这样既享受生态红利又不把命脉交出去。至于skills 开发这个方向我觉得会越来越像一门手艺。写得好的人能把模糊的经验翻译成精确的指令让 Agent 稳定产出高质量结果。这种能力本质上和写文档、做流程设计是一回事只是对象从人变成了 AI。对开发者来说这可能是接下来几年很值得投入的一项技能。最后分享一个我自己的小习惯每次写完一个 skill我会故意用一句模糊的指令去测试它看会不会误触发再用一句精准的指令测试看能不能正确加载。这两个测试过了这个 skill 才算能用。听起来麻烦但比事后收拾烂摊子省事多了。