最近团队里开始大规模用 AI 编程 Agent 写代码大家吐槽最多的反而不是“它不会写代码”而是“写出来的东西一股 AI 味”命名风格东一榔头西一棒子、依赖随手乱加、Git 提交信息写得像机翻、明明团队内有统一的技术栈和约定它偏要用自己训练数据里的那套来。说白了一个会写代码的 Agent 和一名能直接加入项目干活的同事之间差的不是代码能力而是对团队规范的理解和遵守。Skills 机制就是补上这段差距的关键。它相当于给 Agent 预置了一套“岗位手册”把你们项目里的代码规范、提交规范、架构约定、常用方案全部转换成 Agent 能读取、能执行的操作规程。这篇文章我会从实战角度拆解怎么把 Skills 用起来让 Agent 从“会写代码的工具”变成“按规范干活的同事”。1. 先搞清楚 Skills 到底解决了什么问题1.1 通用 Agent 的“能力幻觉”和“规范盲区”很多人第一次用 Claude Code、Codex 这类工具时会觉得它“什么都会”。但实际上它会的只是“写代码”这个泛化能力对你们团队的具体约定一无所知。举个最常见的例子团队后端统一用 Java 17 Spring Boot接口返回结构固定是{ code, message, data }可你让 Agent 生成一个查询接口它很可能会按照自己训练语料里最常见的写法给你返回一个直接丢实体类的结构甚至用上 Java 8 的LocalDate处理逻辑和团队里的工具类完全脱节。再比如前端团队已经定了用 Vue 3 TypeScript unplugin-auto-import组件里不允许手动import { ref } from vue。但通用 Agent 生成的代码大概率会把这些 import 全部写上你还要花时间一行行删。这些小问题叠加起来写代码的时间是省了Review 的时间反而变长了。Skills 解决的就是这种“规范盲区”。它的核心思路不是教 Agent 更多编程知识而是把你们项目里那些“默认大家都该知道”的事情显式地写给 Agent 看。1.2 Skills、Prompt 和 Rules 三者的边界刚开始接触 Skills 的人容易把它和普通的 Prompt 指令、Rules 规则混淆。我自己的理解是这样Prompt 是一次性的对话上下文告诉 Agent“这一次任务怎么干”不持久换个会话就失效。Rules 是全局的行为约束相当于公司的“员工手册”规定哪些能做、哪些不能做通常放在项目根目录的规则文件里每个会话都会加载但它偏“禁止性条款”不适合承载太长的操作细节。Skills 是可复用的“岗位操作手册”围绕某一个具体任务封装完整的步骤、模板、示例和脚本Agent 遇到相关任务时再动态调用相当于“遇到这种情况按这个流程走”。用团队来类比Rules 是“上班不能迟到、代码必须过 Lint”Prompt 是“今天把登录模块改一下”Skills 则是“新同事入职后给他一份怎么提 PR、怎么写 commit message、怎么跑测试的标准化流程文档”。三者配合Agent 才算真正融入团队。2. 项目级 Skills 适配的整体设计思路2.1 先盘点团队里有哪些“隐性规范”做 Skills 适配的第一步不是急着写文件而是先盘点。我建议把团队里大家约定俗成、但从未写进文档的规范都列出来至少包括这些维度代码风格缩进、命名、注释语言、是否强制类型标注、Lint 规则。技术栈约束规定使用的框架版本、UI 库、HTTP 客户端、序列化方式、数据库访问层。架构模式分层方式、目录结构、依赖注入风格、异常处理策略。工程流程Git 分支命名、commit message 格式、PR 描述模板、测试要求、构建命令。业务约定接口返回结构、错误码规范、日志格式、敏感信息脱敏要求。有一个很实用的做法找团队里代码 Review 最严格的那个同事问问他平时都会挑出哪些问题。我当初做适配的时候就是从几个“Review 狠人”的评论里提取出高频意见然后逐个转成 Skills。这样出来的适配目录基本就是团队真实痛点的映射。2.2 确定 Skills 的目录和命名规范目前各家 Agent 对 Skills 的目录约定不完全一致但主流形式大同小异通常是在项目根目录创建一个skills文件夹有的工具是.claude/skills有的是./skills每个 Skill 一个子目录。我建议命名全部用小写字母加连字符例如backend-api-handler、git-commit-convention、vue3-component-style。每一个 Skill 目录下必须有SKILL.md文件这是 Agent 读取的核心入口。其他辅助资源可以包括模板文件、示例代码、可执行的校验脚本等。这里有一个关键点目录名要能体现“场景”而不是“知识点”。比如python-coding-style就太泛了Agent 不知道该什么时候用它改成python-backend-api-implementation就更明确——当需要写 Python 后端接口时使用。Skills 的一个重要特性就是按需加载描述越精确Agent 判断“该不该用”的准确率越高。2.3 分层适配团队级、项目级、个人级Skills 不一定都要塞在项目里。我实际工作中是分三层的团队级 Skills放在一个独立的 Git 仓库里统一管理项目通过 submodule 或复制方式引入。这类 Skills 包含团队的通用规范比如 Git 提交规范、代码 Review 检查清单。项目级 Skills放在具体项目仓库里包含和这个项目强相关的模式比如“这个项目特有的分页返回结构”、“用户权限校验的写法”。个人级 Skills放在你的用户目录下是个人偏好比如你习惯用什么测试框架写单测、喜欢在代码里加什么注释风格。分层的好处是避免把团队规范复制到几十个仓库里改一处其他不同步。我当前的做法是团队级和项目级分开维护个人级基本不用因为既然是希望 Agent “按团队规范干活”个人偏好最好别混进来否则输出又变得不稳定。3. SKILL.md 写作要点把规范翻译给 Agent 听3.1 SKILL.md 的标准结构一个能被 Agent 准确理解的 SKILL.md我一般按下面的结构来写--- name: backend-api-implementation description: 当需要实现一个后端 HTTP API 接口时使用包括 Controller、Service、Mapper 的代码生成和异常处理。不要在处理非接口任务时使用。 --- # 后端 API 接口实现规范 ## 适用场景 - 新增一个 RESTful 接口 - 修改已有接口的返回结构 ## 技术栈与依赖 - 使用 Spring Boot 3.xJava 17 - HTTP 响应统一为 ResponseResultT禁止直接返回实体类 ## 实现步骤 1. 先阅读 src/main/resources/api-schema.yaml 中的接口定义 2. 在 controller 包下新建类... 3. ... ## 验收清单 - [ ] 所有接口都有 Validated 参数校验 - [ ] 使用项目内的 BizException 抛出业务异常 - [ ] 新依赖有正当理由并更新 dependencies.md ## 示例代码 参考 examples/user-controller.example.java注意YAML frontmatter 里的name和description是 Agent 判断是否加载这个 Skill 的重要依据可以写得详细但不要讲废话。特别是 description 里要写清楚“什么时候不该用”这能明显减少误触发。3.2 用“验收清单”代替“讲道理”我踩过最大的坑就是在 SKILL.md 里试图给 Agent“讲道理”——“代码应当具有良好的可读性”、“注意边界情况”。这种大而化之的话对 Agent 约等于没说它不知道你的“可读性”具体指什么。后来我把所有规范全改成可以打勾的验收项。比如“具有良好的可读性”改成方法长度不超过 80 行超过时拆分禁止使用魔法数字常量统一放在Constants.java不允许出现逻辑与超过两层的嵌套条件如有需要提前 return这种清单式写法有两个好处一是 Agent 能在完成代码后自行对照检查二是你在 Review 时拿同一份清单去核对人机标准一致扯皮概率大幅下降。3.3 在 SKILL.md 里嵌入“反面示例”只有正面示例是不够的。Agent 很擅长模仿格式但容易忽略哪些写法是被禁止的。我建议每个 Skill 里都加一个“反面示例”小节展示团队代码里经常出现的坏味道并写明为什么不推荐。举一个实际的例子我们的前端 Skill 里有这么一段## 反面示例 ❌ 在组件里手动导入 Vue API ts import { ref, computed } from vue✅ 正确做法项目已配置 unplugin-auto-import直接使用ref和computed即可。这个技巧的效果非常明显。Agent 生成代码时只要在上下文里看到反面示例就很少再踩同一个坑。我甚至觉得反面示例比正面示例更值得写因为大部分 Agent 的“基础编码能力”已经不错了缺的是对团队禁忌的了解。 ## 4. 实操把高频场景做成 Skills 套件 ### 4.1 场景一Git 提交规范适配 Git 提交信息是 Agent 最容易“放飞自我”的地方。我见过它提交 “update code” 这种毫无信息量的信息也见过它写一整段英文散文。后来我写了一个 git-commit-convention Skill内容很简短 markdown --- name: git-commit-convention description: 在生成 Git commit message 时使用。团队采用 Conventional Commits 规范。 --- # 团队 Git 提交规范 - 格式type(scope): subject - type 使用feat / fix / docs / style / refactor / test / chore - scope 使用模块名例如feat(user-service): 增加用户注销接口 - subject 用中文描述不要用句号结尾不超过 50 个字 - 禁止使用 “update”、“modify” 这类无意义动词这个 Skill 很短但价值很高。它配合 Agent 工具的auto-commit功能基本能保证每一条提交信息都符合团队规范。写这类 Skill 的秘诀就是只列规则不要长篇解释Agent 提取规则的能力很强反而是大段文字会稀释重点。4.2 场景二后端接口代码规范适配如果你们团队有比较严重的接口风格不统一问题可以写一个backend-api-implementationSkill。这个 Skill 通常是最复杂的因为它往往和项目的具体技术栈绑定。我在工程里是这样组织的目录结构skills/ backend-api-implementation/ SKILL.md templates/ Controller.java.tpl Service.java.tpl Mapper.java.tpl examples/ user-controller.example.java user-service.example.javaSKILL.md 重点写三部分接口处理流程、统一响应结构、异常处理规则。模板和示例代码则给出骨架和标准写法。这样 Agent 生成时相当于“照着模板填业务”生成结果非常稳定。整个团队收益最大的地方在于以前不同人写出来的接口参数校验有的用Validated有的手写 if异常有的抛BizException有的直接返回 null现在所有 Agent 生成的接口都是同一套结构Review 成本直线下降。4.3 场景三前端组件开发适配我还写过一个vue3-component-implementationSkill解决的是组件库使用不规范的问题。我们的项目引入了 element-plus但团队内部又封装了一些通用组件比如ProTable、ProDialog有些 Agent 不知道这些封装的存在直接去用原生 table 和 dialog 拼。Skill 里我写明了优先使用团队封装的 Pro 组件不直接使用 element-plus 原生组件实现表格和弹窗组件样式统一使用 scoped CSS 变量不用!important通用状态用 Pinia不要用组件间事件总线所有表单必须有rules校验校验规则集中在validate.ts写这个 Skill 时最好附带 Pro 组件的 props 说明文档和最小示例。Agent 有了参考文档后生成的组件代码基本可以直接用不再需要你一遍遍提醒“用 ProTable 啊”。4.4 场景四数据库访问层规范适配数据访问层的规范通常和具体 ORM 绑定。比如我们团队禁止在 Mapper XML 里写复杂的动态 SQL复杂查询必须走 QueryWrapper 或者在 Service 层用 Java 代码处理。这个规则如果不写进 SkillAgent 很容易生成一长串if标签的 SQL维护起来非常痛苦。数据库访问层 Skill 里我还会写明表和实体类的命名规则、字段类型映射约定、逻辑删除字段的处理方式。这类规范如果在代码 Review 时逐条讲给 Agent 听效率太低写成 Skill 一次配置后面所有会话都能稳定生效。5. 把 Skills 接入日常工作流的几种方式5.1 最简单的方式项目根目录加说明对于 Claude Code 这类工具官方支持自动发现项目里的skills目录。其他 Agent 工具也大多支持类似的机制。你在项目根目录放好 Skills 目录之后新建会话时 Agent 就会先扫描可用的 Skills然后在对话中根据用户请求自动匹配。用起来之后你会发现Agent 在响应任务前有时会主动说一句“我会参考项目里的 xxx Skill”。如果没看到这句话而你确定当前任务应该匹配某个 Skill可能就是因为 description 写得不够精确或者目录没放对位置。5.2 把 Skills 和 Rules 串起来用Rules 通常只适合写一些全局性的、不依赖具体场景的硬约束比如“禁止将敏感配置硬编码在代码里”“所有对外接口必须记录日志”。具体到某个场景怎么做再扔给对应的 Skill。我的经验是Rules 里写“不做什么”SKILL.md 里写“应该怎么做”。两者配合最大的好处是Agent 先通过 Rules 守住底线再通过 Skills 把活干到符合团队的期望效果比只用一种好很多。5.3 用脚本自动校验 Skills 是否生效Skills 不生效是常见问题单纯靠聊天确认不够。我在工程里加了一个很轻量的 Node 脚本每次 Agent 生成完代码后会自动执行项目已有的 lint 和测试。前端跑 eslint vue-tsc后端跑 mvn test。只要有一项不过就要求 Agent 必须修复到通过为止。这个机制虽然不复杂但能倒逼 Agent 认真读取 Skill 里写的内容。尤其当我在 SKILL.md 里写了“代码必须通过以下命令校验”之后Agent 会在生成时主动检查自己有没有违反规范出错率骤降。5.4 不同 Agent 工具间的通用化我知道很多团队不止用一种 Agent 工具有人用 Claude Code有人用 Codex还有人用 Cursor。好消息是 Skills 的理念已经非常通用很多工具都支持只是加载方式略有差异。我的做法是维护一份标准的skills目录然后在不同工具里做适配。比如 Cursor 圈定规则的方式是.cursor/rules我可以在里面写一个很瘦的规则文件内容只有一句“遇到前端组件开发任务时阅读skills/vue3-component-implementation/SKILL.md”。这样不同的工具最终都指向同一份权威文档避免各搞一套导致口径不一致。6. 常见问题与排查技巧实录6.1 Skills 完全没被触发这是我被问得最多的问题。经过排查大部分情况出在 description 写得不够具体Agent 判断不了当前任务属于哪个 Skill。比如我有一个 Skill 的 description 写的是“处理前端相关任务”结果 Agent 几乎从不加载它因为“前端相关”太宽泛了连 Agent 自己都不知道什么时候该用。后来我把 description 改成“当需要实现或修改 Vue 3 组件时使用包括新增页面组件、通用组件不适用于样式调整、工具函数编写”触发率就正常了。另外还要确认 Skill 目录有没有被正确扫描有些工具要求skills目录放在项目根目录有些则需要在配置文件中显式声明路径这一步很容易被忽略。还有一个细节如果你某个 Skill 加了 external 依赖或者引用了本地脚本要确保这些资源路径是相对目录写的不要用绝对路径。否则复制到别的机器上就会因为路径失效导致 Skill 加载失败。6.2 SKILL.md 太长导致 Agent 执行到一半“失忆”刚开始我把 SKILL.md 写成了一篇几千字的百科全书想覆盖所有情况结果 Agent 在处理任务时上下文被大量挤占反而忽略了关键步骤。后来我学乖了每个 SKILL.md 尽量控制在 200 行以内只保留必须的步骤和验收项那些更细节的内容放到同目录下的参考文档里需要时再让 Agent 读取。你可以把 SKILL.md 理解成一个目录索引它告诉 Agent “先去读哪个文件、按照什么顺序操作”而不是把所有信息都塞进去。这个调整之后Agent 的执行稳定度提升非常明显。6.3 多个 Skills 之间产生冲突当项目里的 Skills 数量变多以后冲突是难免的。比如一个backend-api-implementation里要求所有接口使用POST方法另一个restful-api-design里又说查询接口应该用GET。Agent 同时加载两个 Skill 时就会左右为难生成结果随机性很大。我处理冲突的原则是每个场景只设置一个唯一权威的 Skill其他 Skill 引用它而不是重复定义。如果确实需要例外就在对应的 SKILL.md 里显式写“本规范优先于 xxx Skill”。这种“唯一权威”的策略能让 Agent 在做判断时有明确的优先级依据不会出现两套标准打架的情况。6.4 生成的代码仍然不完全符合预期Skills 能大幅提升一致性但不可能保证 100% 符合预期。遇到这种情况我的处理方法是先把部分正确的结果收下然后针对具体的偏差补充 SKILL.md 里的示例或验收清单下一次生成就会好很多。这其实是一个持续迭代的过程Skills 的质量是在一次次 Review 中越磨越好的。另外一个容易被忽略的点是任何 SKILL.md 里写的指令都要确保 Agent 有足够的工具和权限去执行。比如你要求它跑测试但它所在的执行环境没有安装测试依赖那这个验收项永远过不了。所以 Skill 里的每一个操作步骤都必须在真实环境里手动跑一遍验证。7. 关于 Skills 适配我最后的几点个人体会做 Skills 适配这件事最难的其实不是技术而是梳理出团队“真正在用的规范”。很多规范连团队成员自己都没意识到比如代码风格、命名习惯、模块划分逻辑它们分散在不同的代码和 Review 记录里。把这一层隐性知识显性化无论对 Agent 还是对新入职的同事都是巨大的效率提升。我也建议别想着一口气把所有场景都适配完。先挑两三个最高频、最痛的点比如 Git 提交规范和接口代码规范做出效果给团队看然后慢慢扩展。搞得太重太全一方面维护成本高另一方面 Agent 加载时也会犯选择困难症。最后一个小技巧每次让 Agent 干活时可以在对话里显式提一句“先参考项目里的 xxx Skill”。这个动作能帮你快速验证 Skill 是否能被正确触发同时也能给 Agent 一个明确的行为锚点。用久了你会发现Agent 不再像是“一个外部的生成器”而更像一个熟悉你们项目、知道分寸感的协作者。