1. 从skills这个词说起它到底指什么第一次看到skills这个标题很多人会以为是某个泛泛的能力清单或者一份简历上的技能罗列。但结合热搜词里高频出现的 Claude Code、Codex、agents、plugin 这些词基本可以判断这里的 skills 指的是AI 编程代理agent体系里的技能模块——一种把可复用的操作流程、领域知识、工具调用方式打包成标准单元让 agent 在需要时按需加载的机制。说白了它解决的是一个很现实的问题大模型本身很聪明但它不知道你团队内部的代码规范、不知道你们部署流程里那几个必须手动执行的步骤、不知道某个内部 API 的鉴权方式。你每次对话都要重新解释一遍效率极低。skills 就是把这些隐性知识固化下来变成 agent 可以自动识别并调用的能力包。我最初接触这个概念的时候是在给一个前端项目做自动化重构。当时想让 agent 帮我批量处理组件迁移结果它每次都把旧的样式写法带进来反复纠正了七八轮还是记不住。后来我把迁移规则、目标写法、禁止使用的 API 全部写成一个 skill 文件问题一次性解决。从那以后我就意识到skills 的本质不是教模型变聪明而是把上下文工程化。这篇文章适合三类人看一是刚开始用 Claude Code、Codex 这类工具还在靠纯对话干活的人二是团队里想把 AI 编码流程标准化、沉淀下来的技术负责人三是想自己开发 skill、接入到 agent 工作流里的进阶玩家。不管你是哪一类下面这些内容都是我在实际项目里踩过坑之后总结出来的不是照搬文档。2. skills 的运行机制为什么它比写长提示词更靠谱2.1 提示词堆砌的瓶颈在哪里大多数人刚开始用 AI 编程工具习惯是把所有要求塞进一段超长提示词里。比如你要用 TypeScript 严格模式、组件必须用函数式、样式用 CSS Modules、不要用 any、错误处理统一走 logger。短时间看没问题但一旦项目变大这段提示词会膨胀到几千字带来三个直接后果第一上下文窗口被挤占。模型能处理的 token 是有限的你把大量篇幅花在重复的规则说明上真正需要它理解的业务代码就没空间了。第二规则之间会互相干扰。提示词越长模型越容易顾此失彼你强调了 A 规则它可能就忽略了 B 规则。这不是模型笨而是注意力机制本身的特性。第三无法复用和版本管理。提示词散落在各个对话里改了一版不知道旧版在哪团队协作时更是灾难。2.2 skill 的分层加载逻辑skills 机制的核心思路是按需加载、分层组织。一个典型的 skill 通常包含几个部分元信息metadata名称、描述、触发条件。这部分体量很小会常驻在 agent 的上下文里让它知道有这么个技能存在。主体指令instructions具体怎么做什么步骤什么约束。这部分只在 skill 被激活时才加载。附属资源resources脚本、模板、参考文档。需要时才读取。这个设计和操作系统的动态链接库很像——不是所有代码都塞进内存而是用到哪个加载哪个。我实测下来一个组织良好的 skill 体系能把常驻上下文的体积压缩到原来的十分之一左右同时规则遵守率反而更高因为每条规则在它该出现的时候才出现干扰更少。2.3 触发机制agent 怎么知道该用哪个 skill这是很多人困惑的点。agent 判断是否调用某个 skill主要靠描述文本的语义匹配。所以 skill 的 description 写得准不准直接决定它会不会被正确触发。我踩过一个坑写了个处理图片压缩的 skill描述写的是优化资源。结果 agent 在处理 CSS 优化时也把它调出来了因为优化这个词太泛。后来改成压缩 PNG/JPG 图片体积调整分辨率和质量参数触发就精准多了。提示skill 的描述要写做什么具体的事而不是属于什么类别。动词加具体对象比抽象名词靠谱得多。3. 手把手搭一个能用的 skill从目录结构到跑通3.1 目录结构怎么定不同工具的 skill 目录约定略有差异但核心结构大同小异。以常见的约定为例一个 skill 通常长这样skills/ my-skill/ SKILL.md # 主指令文件 scripts/ # 可执行脚本 references/ # 参考文档 assets/ # 模板、静态资源SKILL.md是入口里面用 frontmatter 写元信息正文写指令。frontmatter 一般包含 name 和 description 两个必填字段--- name: component-migration description: 将旧版 Class 组件迁移为函数式组件统一使用 hooks 和项目约定的样式方案 --- ## 迁移步骤 1. 识别目标文件中的 Class 组件 2. 转换生命周期方法为对应 hooks ...这里有个细节name 用短横线连接的小写英文别用中文或空格否则某些工具解析会出问题。description 控制在 100 字以内太长会被截断太短触发不准。3.2 指令正文怎么写才有效正文是 skill 的灵魂。我总结了几条实战原则第一用编号步骤不用大段描述。模型对有序列表的执行准确率明显高于散文式说明。把先做 A再做 B最后做 C写成 1、2、3比写成一段话强得多。第二明确禁止项。只告诉模型该做什么不够还要告诉它不该做什么。比如不要引入新的第三方依赖不要修改测试文件这些约束能挡掉大量返工。第三给出输入输出示例。一个具体的 before/after 例子胜过三段抽象说明。模型会模仿示例的格式和风格。第四把易变的部分参数化。如果 skill 里涉及路径、端口、环境名尽量用占位符或让 agent 从项目配置里读取而不是硬编码。3.3 本地验证的完整流程写完 skill 别急着用先做三步验证语法检查确认 frontmatter 格式正确YAML 没有缩进错误。这一步能挡掉一半的低级问题。触发测试构造几个应该触发和不应该触发的场景看 agent 是否按预期调用。我一般会准备 5 个正例、5 个反例。执行测试让 agent 真正跑一遍完整流程检查输出是否符合预期特别是边界情况。实测下来触发测试最容易被跳过但恰恰是问题最多的地方。很多人 skill 写得好好的就是触发不准用起来时灵时不灵最后弃用。4. 那些文档不会告诉你的坑4.1 描述写得太聪明反而触发不了新手容易把 description 写得很有文采比如智能优化代码质量提升工程效能。这种描述语义太宽泛agent 根本判断不出什么时候该用。正确做法是用具体的动作和对象检测并修复 ESLint 报错自动格式化代码。4.2 skill 之间会打架当你有多个 skill且它们的触发条件有重叠时agent 可能选错。比如同时有代码格式化和代码重构两个 skill处理一个既有格式问题又需要重构的文件时它可能只调一个。解决办法是在 description 里明确边界或者在一个 skill 里用条件分支处理不同情况。我现在的习惯是宁可少而精不要多而杂。一个 skill 只干一件事边界清晰。4.3 脚本权限和路径问题如果 skill 里带了可执行脚本注意两点一是脚本要有可执行权限二是脚本里的路径要用相对路径或从环境变量读取别写死绝对路径。我见过有人把/Users/xxx/project写进脚本换台机器直接报错。4.4 版本更新后 skill 失效工具升级后skill 的加载机制、frontmatter 字段可能有变化。建议给 skill 加个版本注释升级工具后先跑一遍验证流程。别等到生产环境出问题才发现。常见问题表现解决方向触发不准该用时不用不该用时乱用收紧 description增加正反例测试执行偏差步骤漏做或顺序错改编号列表加禁止项上下文超限报错或响应变慢拆分 skill资源按需加载跨环境失效换机器就报错去掉硬编码路径和绝对引用5. 把 skills 用进真实工作流几个落地场景5.1 代码规范统一团队里每个人写代码风格不一样review 时吵来吵去。把规范写成 skillagent 在生成代码时自动遵守review 成本直接降下来。关键是规范要写得可执行比如函数参数超过 3 个时用对象传参而不是保持代码优雅。5.2 重复性任务自动化比如每次新建页面都要创建组件文件、路由配置、样式文件、测试文件这一套。写成 skill 后一句话就能生成完整骨架。我算过这类任务单个能省 10 到 15 分钟一天做几次就很可观。5.3 新人上手加速新同事不熟悉项目约定问东问西。把常见操作都做成 skill他直接让 agent 执行边做边学。这比看文档快得多因为 skill 是可执行的文档。5.4 跨工具复用Claude Code、Codex 这些工具虽然各有特点但 skill 的核心逻辑是相通的。把指令和资源组织好迁移成本并不高。我现在的做法是把 skill 当成独立资产维护工具只是执行载体换工具不换 skill。6. 进阶让 skills 真正产生复利6.1 建立 skill 的评估机制不是写完就完事。我会定期回顾每个 skill 的使用频率和成功率。用得少的考虑合并或删除成功率低的重新打磨描述和指令。skill 库和代码库一样需要持续维护不然会变成技术债。6.2 组合使用而非单打独斗复杂任务往往需要多个 skill 协作。比如重构一个模块可能涉及代码分析、迁移、测试三个 skill。关键是让它们的输入输出能衔接上前一个的输出格式要能被后一个识别。6.3 把经验沉淀成 skill这是我觉得最有价值的一点。每次解决一个棘手问题顺手把解决过程写成 skill。时间长了你的 skill 库就是你个人经验的结晶换项目、换团队都能带走。这比写博客、记笔记的复用率高得多因为它是可执行的。6.4 注意安全和边界skill 里如果涉及文件操作、命令执行一定要想清楚权限边界。别让一个 skill 能删库跑路。我的原则是能只读就不写能限定目录就不放开全局。涉及敏感操作的 skill加确认步骤。7. 我踩过的几个真实坑和最终解法说几个具体的。有一次我写了个批量重命名的 skill测试时好好的结果在真实项目里把一批重要文件改错了名。原因是我的指令里没写跳过已符合命名规范的文件agent 无差别处理了所有文件。后来加了前置检查步骤才解决。还有一次skill 里的脚本用了某个只在特定 shell 下可用的语法换到另一个环境就挂了。教训是脚本要写得足够保守用最通用的写法。再有就是触发冲突。我同时装了三个跟测试相关的 skill结果 agent 经常选错。最后合并成一个用条件分支区分单元测试、集成测试、端到端测试问题消失。这些坑的共同点是测试环境和真实环境有差异单 skill 和 skill 组合有差异。所以验证一定要在接近真实的环境里做而且要测组合场景。8. 关于 skills 的几个常见疑问skills 和 plugin 有什么区别简单说plugin 更偏向工具能力的扩展skills 更偏向流程和知识的封装。plugin 给 agent 加手skills 给 agent 加经验。实际使用中两者经常配合。一定要用官方市场里的 skill 吗不一定。官方市场的 skill 通用性强但未必贴合你的项目。我的建议是先用官方的熟悉机制然后针对自己的高频场景写私有 skill收益最大。skill 写多长合适没有硬性标准但我的经验是主指令控制在 500 到 1500 字之间。太短说不清楚太长加载慢且容易失焦。超出的内容拆到 references 里按需读取。多个项目能共用一套 skill 吗通用的可以项目特有的建议分开。我一般分两层一层是跨项目的通用 skill一层是项目专属的放在项目目录里跟着代码走。skill 会不会让 agent 变死板恰恰相反。好的 skill 是给 agent 提供默认最优解遇到特殊情况它仍然可以灵活处理。关键是别把 skill 写成不可变通的死规则留出判断空间。9. 最后分享几个实用技巧第一个技巧给 skill 写反例。在指令里明确写以下情况不要使用本 skill比只写正例有效得多。模型对否定约束的遵守度其实不低前提是你写清楚了。第二个技巧用真实任务测试别用玩具例子。玩具例子太干净掩盖了很多边界问题。直接拿项目里最复杂的那个文件来测能暴露的问题最多。第三个技巧skill 的命名要能自解释。fix-eslint-errors比code-helper好migrate-class-to-hooks比refactor好。名字本身就是给 agent 的提示。第四个技巧定期清理。三个月没用过的 skill要么删掉要么合并。skill 库臃肿了触发准确率会下降维护成本也上去了。第五个技巧把 skill 纳入代码评审。skill 也是代码资产改动应该走评审流程。我见过团队里 skill 被随意改坏导致整个流程出问题的情况。这套东西我用了大半年最大的感受是AI 编程工具的上限很大程度上取决于你怎么组织上下文。skills 就是组织上下文的一种工程化手段。它不神秘本质就是把你的经验、规范、流程用 agent 能理解的方式写下来让它在对的时候做对的事。刚开始可能觉得麻烦但一旦跑顺复利效应非常明显。