1. 会写代码不等于能干活Agent 入职后最让人头疼的差距先讲一个我真实遇到的场景。团队试用 AI Agent 写代码第一个任务很简单给用户模块加一个分页查询接口。Agent 三分钟交了代码能跑接口返回也对。但打开 PR 一看我整个人都不好了——错误处理用的全局异常拦截器它完全没碰日志打在 console.log 而不是团队统一的 Logger变量命名风格和隔壁老代码完全是两种画风commit message 写的是 fix: update user api而我们的规范要求带模块前缀和关联的 issue 编号。最讽刺的是它写出来的代码在语法层面挑不出毛病甚至在 LeetCode 层面是优秀的。但放进我们的工程体系里就是一份需要返工两轮的半成品。这不是 Agent 的能力问题是岗位适配问题。就像你招了一个底子很好的应届生算法能力强但你不给他看团队规范、不告诉他代码评审的检查清单、不带他过一遍 commit 规范和分支命名规则他写出来的东西一定充满个人风格。Agent 也一样它的训练数据来自全世界的开源仓库平均了所有团队的习惯自然写不出“你们团队风格”的代码。这里要引入 Skills 这个概念。Skills 是给 Agent 装的一套可插拔的技能包本质上是把“怎么写代码”这件事从通用能力里拆出来按需挂载。你可以把它理解成给 Agent 上的“入职培训课”教它你们团队的代码风格、目录结构、错误处理约定、提交规范甚至教它哪些文件能碰、哪些文件别动。目标只有一个——让一个“什么都会写的通用程序员”变成一个“按你们规范干活的同事”。为什么传统做法搞不定这件事很多团队试过把规范文档全部塞进 system prompt结果要么上下文爆炸要么 Agent 抓不住重点指令太多反而相互干扰。还有些团队靠人肉在写代码的时候补充“注意用我们团队的 Logger”这等于每次都要人工给 Agent 做岗前培训根本不具备可复制性。Skills 的做法不一样把规范按任务拆成独立的技能包Agent 在遇到对应场景时自动或手动加载用完即走互不污染。这是它在工程层面能落地的根本原因。这篇文章我会从 Skills 的机制原理讲起然后以一套完整的前端项目适配案例演示如何把团队规范翻译成 Agent 能执行的动作清单最后把我踩过的一些坑和推广落地的经验一并交代。想让 Agent 真正从“能写代码”变成“会干活”的团队这篇文章应该能给你一条比较清晰的路径。2. Skills 不是“提示词插件”它是 Agent 的入职手册很多人第一次接触 Skills 时会下意识把它归类为“高级提示词”——无非就是把规范写得更长、更结构化一点。我在实际用下来之后可以明确说这个理解不太对。提示词是一次性发送给模型的文本输入而 Skills 是一套有目录结构、有条件触发、可版本管理的文件集合。它们的差距本质上是一个“告示板”和一套“员工手册”的差距。2.1 Skills 的物理结构SKILL.md 是入口references 是资料库一个标准的 Skill 通常长这样skills/ frontend-vue-component/ SKILL.md references/ component-checklist.md naming-conventions.md error-handling-pattern.md templates/ standard-component.vueSKILL.md 是入口文件里面写清楚这条技能是干什么的、在什么场景下触发、核心流程是什么。references 目录放的是参考资料比如命名规范表、组件检查清单、团队约定的大全。templates 目录放的是模板文件直接给 Agent 一个标准答案的底子。为什么这样设计因为 Agent 的上下文窗口是有限资源。如果一条技能把所有内容都塞进 SKILL.md加载时会占用大量上下文影响它对当前任务的判断力和注意力。更合理的做法是SKILL.md 只写执行逻辑和触发条件把查表类内容放 references把结构类内容放 templates。Agent 在处理任务时先读了 SKILL.md 知道“我要做什么、按什么顺序做”然后按需打开 references 里的某个参考资料或者直接引用 templates 里的模板。这就像新员工入职第一天你先给他一页纸的“上岗须知”里面写着工作流程和找谁对接而不是直接甩给他一整本二十万字的公司制度汇编。他需要了解报销流程时再去翻制度手册的对应章节而不是第一天就背完整本书。2.2 加载时机按需挂载用完即走和 system prompt 最大的区别在于加载时机。system prompt 是全程在场的无论 Agent 在执行什么任务它都能看到你写的所有规范。听起来很美好但实际效果是指令太多注意力被稀释Agent 反而分不清哪些是必须遵守的、哪些只是参考。Skills 的逻辑是按需挂载。Agent 分析当前任务时会先判断这个任务和哪些技能相关然后把对应的 SKILL.md 加载进上下文。比如我现在让它写一个 Vue 组件它发现这个任务触发了 frontend-vue-component 这条技能就去读技能的入口文件再决定要不要深挖 references。如果让它写一个 Node.js 脚本它就完全不会加载 Vue 组件相关的技能上下文里不会有一堆无关的组件规范抢注意力。这一点我用一个比方来解释资深的工程师在写 API 路由时脑子里只会想着接口设计规范和错误处理约定并不会同时回忆组件命名要用 PascalCase 还是 kebab-case。Skills 就是模拟这种“场景化调取经验”的机制。2.3 Skills、system prompt、团队 Wiki 三者边界要分清我见过不少团队把 Skills 当成团队 Wiki 的搬运工——把整个开发规范文档直接拆成几个 Skill 塞进去效果一塌糊涂。这三者的定位完全不同。载体定位优点缺点system prompt全局总纲Agent 的行为底线全时在场适合放不可违背的约束内容一多就稀释互相干扰Skills场景化的操作手册按任务加载精准、低干扰、可组合、可版本化需要设计和维护成本团队 Wiki给人看的完整资料库信息完整、便于人阅读Agent 直接读会很吃力缺少执行导向我的实践经验是system prompt 里只放“不能做”的硬约束比如不能删除未确认的文件、不能把密钥硬编码 Skills 里放“应该怎么做”的操作细节团队 Wiki 保留给人看但每个 Skill 可以挂一个 Wiki 链接作为深度参考。三者各司其职谁也不要想着替代谁。Skills 的真正价值在于它把一个团队的隐性知识——那些分布在代码评审意见里、新人踩坑总结里、老员工口口相传里的经验——显性化、结构化成 Agent 可以直接执行的步骤。这比单纯“塞文档”高一个维度你给 Agent 的不只是知识还包括了知识的调用方式和执行边界。3. 把团队规范翻译成 Skills一个前端项目的完整适配过程接下来用一个实际案例完整走一遍适配过程。这个案例是前端工程团队目标是让 Agent 能按团队规范开发 Vue 组件。我会从规范盘点、翻译、搭建目录、验证四个阶段来推进。3.1 第一步盘点规范先做减法再做加法团队规范通常有一大堆但并不是每条都值得做成 Skill。我的原则是三条筛选标准CI 已经能检查的不写进 Skill。比如 ESLint 规则、Prettier 风格、依赖版本检查这些工具会自动拦截Agent 写出不合规的代码也会在流水线里被卡住写进 Skill 只会浪费上下文。Skill 里只要写一句“依赖命令行工具执行 lint 检查按提示修复全部 error”。Agent 天生就会的不写进 Skill。比如基本的 Vue 语法、组件生命周期、响应式原理这些模型训练时已经掌握得很好了写进去纯属重复。只有“会对队友造成困扰”的约定才值得写。如果 Agent 违反了这些约定会产生真实的协作摩擦比如命名风格不统一、错误处理方式五花八门、提交信息混乱、组件拆分的颗粒度失控。按这个标准筛选下来一个前端团队的规范通常剩下这几条最值得做成 Skill组件目录与命名约定、组件 props / emits 的设计约束、错误处理和加载态的统一方案、提交信息格式规范、代码评审的快速自查清单。3.2 第二步把“规范描述”翻译成“Agent 能执行的动作”这一步是核心难点。团队规范文档里的描述往往是意图导向的比如“组件命名要清晰统一”。这种话人看懂没问题但 Agent 不知道该具体执行什么。所谓翻译就是把意图导向的描述转成动作导向的指令。我拿团队规范里的几条真实描述做个翻译示例团队规范原文给人看Skill 里的可执行指令给 Agent 看验收判断组件命名要统一新建组件时文件名用 kebab-case组件导出名用 PascalCase文件名须和路由路径的最后一个目录名语义一致脚本检查文件名与导出名匹配度所有对外接口必须做参数校验当组件接收 props 时必须声明 type、default、validatorprops 变更须用 emits 向父组件通信禁止直接修改 props人工 review 核对错误处理要统一接口请求失败时统一使用 src/utils/feedback.ts 里的 toastError 方法禁止在业务代码里写 console.error代码检索确认加载态必须有兜底列表类组件必须包含 loading、empty、error 三个状态的 UI手工勾选检查清单翻译成动作指令后Agent 的执行力会有一个质的提升。关键在于验收判断那一列——每一条指令都应该能对应到一个明确的检查动作要么是脚本可以自动完成的要么是代码评审时一眼能看出来的。如果一条规范翻译完之后无法对应任何可检查的信号那说明它还不够具体需要继续拆。3.3 第三步搭建 Skill 目录并编写 SKILL.md做完翻译就可以动手搭目录了。还是用前端的例子我在项目 .team-skills 目录下建了 frontend-vue-component 这块技能配套的还有 frontend-commit-message、frontend-review-checklist 两个技能。这里先展示 SKILL.md 的骨架--- name: frontend-vue-component description: 按团队规范开发或修改 Vue 组件时使用 applies_to: .vue, .tsx, .jsx --- # Vue 组件开发规范 ## 什么时候用 - 新建页面级组件或业务组件 - 修改现有组件的 props、emits、样式方案 - 重构组件拆分的颗粒度 ## 执行步骤 1. 阅读 templates/standard-component.vue以此为基底 2. 确认目录归属页面组件放 views/ 下对应路由目录业务组件放 components/ 3. 文件命名 kebab-case导出名 PascalCase 4. props 必须声明 type、default、validator需要父组件响应的一律走 emits 5. 接口请求统一走 src/api 下的封装失败时调用 feedback.ts 的 toastError 6. 列表类组件必须包含 loading、empty、error 三态 7. 完成后对照 references/component-checklist.md 逐项自查 ## 重要禁忌 - 不要直接修改 props 对象 - 不要在业务代码中直接使用 console 打日志 - 不要引入新的 UI 组件库统一走项目已有的 design system注意几个细节一是加了 frontmatter 头写清楚技能名称和适用场景这样 Agent 在任务判断时才能准确匹配二是执行步骤编号化Agent 对编号指令的跟随能力明显强于纯段落描述三是“重要禁忌”单独成节负向约束比正向引导更省 token效果也更直接。我把组件命名规范、错误处理细则这类需要查表的内容放到了 references 目录SKILL.md 里保持精简只留主流程。一个技能的主文档最好控制在 50 行以内超过这个规模就要考虑是不是拆技能了。3.4 第四步分层适配——项目级、团队级、组织级在实际推广中我很快发现只做一个项目级的 Skill 是不够的。团队里不可能只有一个项目而不同项目之间规范有共性的部分也有各自特殊的部分。全堆在一个技能里项目 A 的规范会污染项目 B。我把 Skill 分成三个层级来管理项目级.project-skills/只属于当前仓库的约定比如这个项目用了 Vue2 还是 Vue3、用的是 Element Plus 还是 Ant Design Vue、目录结构是按业务模块划分还是按技术类型划分。这类技能落地在当前项目仓库内的隐藏目录里跟着仓库走不对外分发。团队级团队共享仓库团队通用的工程规范、代码风格、组件设计约束、提交流程。这类技能放在一个独立的 team-skills 仓库里由团队成员共同维护各项目通过构建脚本拉取。组织级公共技能市场多个团队都会用到的通用规范比如安全编码规范、日志规范、数据库访问规范。这类技能通常由平台工程团队统一维护。加载顺序上组织级和团队级是基础底料项目级是定制补丁项目级技能的文件描述和指令优先级要高于团队级。这样可以处理一个实际问题团队通用规范说“全面使用 Vue 3 Composition API”但某个老项目还在用 Vue 2 Options API那么这个项目目录下的项目级技能就要明确覆盖这一条写“本项目保留 Options API 风格禁止在现有 Options API 组件中混用 Composition API”。Agent 在加载技能时项目级的指令要能压过团队级的默认约定。3.5 第五步验证效果用一个小任务试水Skill 建好之后不要直接全员推广先用一个真实任务验证。我在试点项目里给 Agent 抛了个小需求新增一个“用户详情”的弹窗组件。它需要根据接口返回渲染用户信息包含加载中和空数据状态。没有挂载 Skill 之前Agent 写出的组件是自由发挥的文件名用了 PascalCaseprops 没写 validator接口请求直接写在组件内部失败时 console.error。加上 Skill 之后同一任务的结果差异非常明显组件被正确放到了 views/user/components/ 目录文件名是 user-detail-dialog.vueprops 有完整的类型声明和 validator接口调用走了封装好的 api 函数错误处理用的统一的 toastError三态 UI 齐全。这个对比直观说明了 Skills 的价值不是让 Agent 从“不会写”变成“会写”而是从“会写”变成“写得符合团队的协作方式”。这也是我说的把“会写代码的 Agent”变成“会按规范干活的同事”的本质。4. 适配期的真实翻车清单我踩过的坑和绕坑姿势Skill 适配并不是一帆风顺的。我在几个团队推广的过程中踩了不少坑有些问题极具迷惑性不实际跑一遍根本想不到。挑几个最有代表性的说一下。4.1 坑一一个巨型 Skill 试图搞定所有前端任务第一个版本我图省事把前端所有规范全部写进了一个 frontend-developer 技能里。SKILL.md 写了三百多行包含组件开发、样式方案、状态管理、路由配置、接口请求、提交规范甚至还有代码评审清单。看起来挺全面实际用起来一塌糊涂。表现主要有两个首先上下文占据过大Agent 在处理一个简单的样式调整任务时也要加载全部三百行内容相当于让它背完整本规范再开始写一行 CSS。其次指令之间互相干扰Agent 经常在完成一个任务时“顺便”遵守了无关的规范反而干扰了主要工作。解法是拆技能。把一个大技能拆成功能内聚的小技能每个技能只负责一类场景写组件就加载组件技能提交代码就加载提交规范技能代码评审就加载审查技能。技能之间的边界越清晰Agent 的调用准确率越高。4.2 坑二全局技能和项目实际情况打架团队级技能里写了“新组件一律使用 Composition API”但某个老项目还是 Options API 风格。Agent 按团队技能干活新建的组件和周围老代码格格不入code review 被打回。这个坑的根因在于技能设计时没有考虑不同项目的语境差异。解法就是前面说的分级适配和优先级覆盖。团队级技能要主动留出可以被项目级技能覆盖的口子在文档里写明“如项目有特殊约定以项目内 .project-skills 为准”。项目级技能里遇到冲突的条目直接写明覆盖逻辑和原因。Agent 加载冲突时不会凌乱因为它有明确的优先级规则。4.3 坑三写了没法验证的规则还有一个很典型的坑Skill 里写了一堆“高质量”“优雅”“合理”这类主观形容词比如“代码要优雅”“异常处理要合理”。这些话模型无法精确执行因为“优雅”和“合理”没有明确的判断标准。结果就是 Agent 看似遵守了实际上没有任何改变该被评审打回的照样打回。后来我给自己定了一条规矩每条 Skill 里的指令都必须能对应到一个可检查的信号。要么是自动化的脚本、代码检索、正则匹配要么是人工 review 时一眼能看出来的明确条件。写不出验收标准的指令一开始就不应该写进去。4.4 坑四规范更新了Skill 没跟着同步团队规范是动态变化的。某个季度组件库从 2.x 升级到了 3.xAPI 有破坏性变更。人在团队里通过公告和代码评审逐渐接受了新用法但 Skill 里写的还是旧 API。Agent 以后的代码越写越“过时”。这个坑不能靠自觉来防要靠机制。我现在的做法是把规范文档和 Skill 放进同一个仓库同一套变更流程团队规范文档的 MR 必须连带更新对应的 Skill 文件由同一个 reviewer 把关。如果 Skill 没法随规范同步更新那就干脆先不建这条 Skill。4.5 坑五上下文预算失控技能加载过多技能拆得太细也有副作用。一次任务里Agent 可能同时匹配到组件开发、样式方案、接口请求、提交规范等多个技能。如果每个技能都加载主文档和全部参考资料上下文很快就满了反而没空间思考业务逻辑。我采取两个控制手段一是技能文档瘦身SKILL.md 控制在 30 到 60 行参考资料里的内容让 Agent 按需打开不由主文档一次性拉取二是在 description 字段里写清楚触发条件越精确越好。比如“仅在新建组件或修改 props 时使用”这样无关任务就不会误触发这个技能。上下文是 Agent 最宝贵的资源技能加载和它是一笔账每一块上下文都要花在刀刃上。5. 从一个人适配到全项目铺开Skills 仓库的运营与迭代当你在一个项目里把 Skills 跑通之后接下来的问题就变成了怎么让整个团队都用起来并且持续维护让这些技能不腐烂。5.1 把 Skills 当代码工程来管理而不是文档收集Skills 最容易被当成“写给大家看的文档”但实际上它应该被当成代码来管理。我的做法是在团队内部建了一个 team-skills 仓库目录结构按技能用途分好每个 MR 必须经过评审合并有版本发布有变更记录。评审 skill 的 MR 和评审普通代码 MR 看的东西不一样。我看三点指令是否能被 Agent 稳定执行有没有含糊的主观描述技能之间是否有冲突有没有重复覆盖的领域上下文消耗是否合理能否再瘦身。三个维度都过关才会合进去。5.2 用“技能质量评分卡”来衡量 Skill 的优劣技能维护最怕的是“建了没人管后来没人用”。我给团队设计了一个简单的评分卡每个季度审视一轮。评分的维度不复杂但很实用维度衡量方式合格线触发准确率Agent 加载该技能的任务中确实需要它的比例 80%扰动率加载该技能的任务输出被 review 打回的比例低于不加载时文档新鲜度Skill 内的指令和当前团队规范是否一致无过时条目上下文效率技能平均加载体量 / 有效指令比例主文档 60 行被判定为长期无人触发或者反而拉低效率的技能我会直接下架。技能不是越多越好维护一个“少而精”的技能库比堆一大仓库没人用的死技能健康得多。5.3 和 CI 流水线分工能自动挡的不要靠技能手挡Skills 不能替代工程基础设施。我的切分原则是凡是 CI 可以自动检查的规范一律交给 CISkills 里只需要提示 Agent 执行对应的脚本并处理结果。只有那些必须靠理解任务结构才能做对的决策才需要写进 Skills 引导 Agent 判断。举个例子提交信息的格式。我在 Git 的 commit-msg 钩子里已经做了一整套校验不符合规范直接拦截。Skill 要做的事情不是把规范写一遍而是告诉 Agent“提交前要阅读提交信息规范并按照规范填写CI 会校验”。这样 Skill 就不需要把每一种提交类型都列出来反而省下上下文。5.4 用数据说话适配前后到底改变了什么团队最关心的一个问题做了 Skills 适配Agent 产出的代码质量到底提升了多少反正我是不信“感觉好多了”这种话的数据才是硬道理。我在试点项目统计了三个月的 MR 数据适配前Agent 产出的 PR 平均要经过 2.7 轮 review 才能合入其中一半的修改集中在错误处理、命名风格和提交信息这类规范问题上适配后平均 review 轮次降到了 1.2 轮规范类修改占返工内容的比例明显下降reviewer 终于可以把精力放在架构设计、边界条件和性能优化上而不是反复纠正格式和风格。还有另一个更易被忽视的价值新人上手时间。“按团队规范干活”这件事人类新人通常要一两个月才能完全形成肌肉记忆。把同样的规则打包成 Skill 传给新人和 Agent 后新人第一次写出符合所有团队规范的代码所需的时间少了很多因为 Rules 是显式写出来的他看一眼就能通晓全局不用自己慢慢从 Review 教训里悟了。5.5 逐步推开的路径别想着一口气吃成胖子如果你准备在团队里推 Skills我的建议是从一条最痛、最容易验证的规范开始。比如提交信息规范或者组件目录规范先做成第一个 Skill 项目让 Agent 在一类任务上明显变合规。验证有效之后再逐步扩展不要一上来就做一个覆盖所有规范的大工程。另外想强调一点Skills 是团队知识资产的一部分它的价值在于持续迭代。今天写的 Skill半年后可能因为技术栈升级、架构调整而失效。把它当代码管当成一个活的项目运营而不是当成一份定稿的文档扔在仓库里这个认知比任何具体技巧都重要。在我自己的项目里现在 Agent 已经能独立承担不少日常开发工作产出的代码在规范契合度上基本和团队里工作了一两年的工程师一个水平。这个过程不复杂但需要耐心先把规范翻译成动作再让动作变得可验证最后把它运作成一个持续更新的体系。这套方法论我认为不止适用于前端任何有明确工程规范、又想让 Agent 深度参与开发的团队都可以参考着做一遍。 让AI Agent从会写代码到会干活：Skills技能包实战指南
1. 会写代码不等于能干活Agent 入职后最让人头疼的差距先讲一个我真实遇到的场景。团队试用 AI Agent 写代码第一个任务很简单给用户模块加一个分页查询接口。Agent 三分钟交了代码能跑接口返回也对。但打开 PR 一看我整个人都不好了——错误处理用的全局异常拦截器它完全没碰日志打在 console.log 而不是团队统一的 Logger变量命名风格和隔壁老代码完全是两种画风commit message 写的是 fix: update user api而我们的规范要求带模块前缀和关联的 issue 编号。最讽刺的是它写出来的代码在语法层面挑不出毛病甚至在 LeetCode 层面是优秀的。但放进我们的工程体系里就是一份需要返工两轮的半成品。这不是 Agent 的能力问题是岗位适配问题。就像你招了一个底子很好的应届生算法能力强但你不给他看团队规范、不告诉他代码评审的检查清单、不带他过一遍 commit 规范和分支命名规则他写出来的东西一定充满个人风格。Agent 也一样它的训练数据来自全世界的开源仓库平均了所有团队的习惯自然写不出“你们团队风格”的代码。这里要引入 Skills 这个概念。Skills 是给 Agent 装的一套可插拔的技能包本质上是把“怎么写代码”这件事从通用能力里拆出来按需挂载。你可以把它理解成给 Agent 上的“入职培训课”教它你们团队的代码风格、目录结构、错误处理约定、提交规范甚至教它哪些文件能碰、哪些文件别动。目标只有一个——让一个“什么都会写的通用程序员”变成一个“按你们规范干活的同事”。为什么传统做法搞不定这件事很多团队试过把规范文档全部塞进 system prompt结果要么上下文爆炸要么 Agent 抓不住重点指令太多反而相互干扰。还有些团队靠人肉在写代码的时候补充“注意用我们团队的 Logger”这等于每次都要人工给 Agent 做岗前培训根本不具备可复制性。Skills 的做法不一样把规范按任务拆成独立的技能包Agent 在遇到对应场景时自动或手动加载用完即走互不污染。这是它在工程层面能落地的根本原因。这篇文章我会从 Skills 的机制原理讲起然后以一套完整的前端项目适配案例演示如何把团队规范翻译成 Agent 能执行的动作清单最后把我踩过的一些坑和推广落地的经验一并交代。想让 Agent 真正从“能写代码”变成“会干活”的团队这篇文章应该能给你一条比较清晰的路径。2. Skills 不是“提示词插件”它是 Agent 的入职手册很多人第一次接触 Skills 时会下意识把它归类为“高级提示词”——无非就是把规范写得更长、更结构化一点。我在实际用下来之后可以明确说这个理解不太对。提示词是一次性发送给模型的文本输入而 Skills 是一套有目录结构、有条件触发、可版本管理的文件集合。它们的差距本质上是一个“告示板”和一套“员工手册”的差距。2.1 Skills 的物理结构SKILL.md 是入口references 是资料库一个标准的 Skill 通常长这样skills/ frontend-vue-component/ SKILL.md references/ component-checklist.md naming-conventions.md error-handling-pattern.md templates/ standard-component.vueSKILL.md 是入口文件里面写清楚这条技能是干什么的、在什么场景下触发、核心流程是什么。references 目录放的是参考资料比如命名规范表、组件检查清单、团队约定的大全。templates 目录放的是模板文件直接给 Agent 一个标准答案的底子。为什么这样设计因为 Agent 的上下文窗口是有限资源。如果一条技能把所有内容都塞进 SKILL.md加载时会占用大量上下文影响它对当前任务的判断力和注意力。更合理的做法是SKILL.md 只写执行逻辑和触发条件把查表类内容放 references把结构类内容放 templates。Agent 在处理任务时先读了 SKILL.md 知道“我要做什么、按什么顺序做”然后按需打开 references 里的某个参考资料或者直接引用 templates 里的模板。这就像新员工入职第一天你先给他一页纸的“上岗须知”里面写着工作流程和找谁对接而不是直接甩给他一整本二十万字的公司制度汇编。他需要了解报销流程时再去翻制度手册的对应章节而不是第一天就背完整本书。2.2 加载时机按需挂载用完即走和 system prompt 最大的区别在于加载时机。system prompt 是全程在场的无论 Agent 在执行什么任务它都能看到你写的所有规范。听起来很美好但实际效果是指令太多注意力被稀释Agent 反而分不清哪些是必须遵守的、哪些只是参考。Skills 的逻辑是按需挂载。Agent 分析当前任务时会先判断这个任务和哪些技能相关然后把对应的 SKILL.md 加载进上下文。比如我现在让它写一个 Vue 组件它发现这个任务触发了 frontend-vue-component 这条技能就去读技能的入口文件再决定要不要深挖 references。如果让它写一个 Node.js 脚本它就完全不会加载 Vue 组件相关的技能上下文里不会有一堆无关的组件规范抢注意力。这一点我用一个比方来解释资深的工程师在写 API 路由时脑子里只会想着接口设计规范和错误处理约定并不会同时回忆组件命名要用 PascalCase 还是 kebab-case。Skills 就是模拟这种“场景化调取经验”的机制。2.3 Skills、system prompt、团队 Wiki 三者边界要分清我见过不少团队把 Skills 当成团队 Wiki 的搬运工——把整个开发规范文档直接拆成几个 Skill 塞进去效果一塌糊涂。这三者的定位完全不同。载体定位优点缺点system prompt全局总纲Agent 的行为底线全时在场适合放不可违背的约束内容一多就稀释互相干扰Skills场景化的操作手册按任务加载精准、低干扰、可组合、可版本化需要设计和维护成本团队 Wiki给人看的完整资料库信息完整、便于人阅读Agent 直接读会很吃力缺少执行导向我的实践经验是system prompt 里只放“不能做”的硬约束比如不能删除未确认的文件、不能把密钥硬编码 Skills 里放“应该怎么做”的操作细节团队 Wiki 保留给人看但每个 Skill 可以挂一个 Wiki 链接作为深度参考。三者各司其职谁也不要想着替代谁。Skills 的真正价值在于它把一个团队的隐性知识——那些分布在代码评审意见里、新人踩坑总结里、老员工口口相传里的经验——显性化、结构化成 Agent 可以直接执行的步骤。这比单纯“塞文档”高一个维度你给 Agent 的不只是知识还包括了知识的调用方式和执行边界。3. 把团队规范翻译成 Skills一个前端项目的完整适配过程接下来用一个实际案例完整走一遍适配过程。这个案例是前端工程团队目标是让 Agent 能按团队规范开发 Vue 组件。我会从规范盘点、翻译、搭建目录、验证四个阶段来推进。3.1 第一步盘点规范先做减法再做加法团队规范通常有一大堆但并不是每条都值得做成 Skill。我的原则是三条筛选标准CI 已经能检查的不写进 Skill。比如 ESLint 规则、Prettier 风格、依赖版本检查这些工具会自动拦截Agent 写出不合规的代码也会在流水线里被卡住写进 Skill 只会浪费上下文。Skill 里只要写一句“依赖命令行工具执行 lint 检查按提示修复全部 error”。Agent 天生就会的不写进 Skill。比如基本的 Vue 语法、组件生命周期、响应式原理这些模型训练时已经掌握得很好了写进去纯属重复。只有“会对队友造成困扰”的约定才值得写。如果 Agent 违反了这些约定会产生真实的协作摩擦比如命名风格不统一、错误处理方式五花八门、提交信息混乱、组件拆分的颗粒度失控。按这个标准筛选下来一个前端团队的规范通常剩下这几条最值得做成 Skill组件目录与命名约定、组件 props / emits 的设计约束、错误处理和加载态的统一方案、提交信息格式规范、代码评审的快速自查清单。3.2 第二步把“规范描述”翻译成“Agent 能执行的动作”这一步是核心难点。团队规范文档里的描述往往是意图导向的比如“组件命名要清晰统一”。这种话人看懂没问题但 Agent 不知道该具体执行什么。所谓翻译就是把意图导向的描述转成动作导向的指令。我拿团队规范里的几条真实描述做个翻译示例团队规范原文给人看Skill 里的可执行指令给 Agent 看验收判断组件命名要统一新建组件时文件名用 kebab-case组件导出名用 PascalCase文件名须和路由路径的最后一个目录名语义一致脚本检查文件名与导出名匹配度所有对外接口必须做参数校验当组件接收 props 时必须声明 type、default、validatorprops 变更须用 emits 向父组件通信禁止直接修改 props人工 review 核对错误处理要统一接口请求失败时统一使用 src/utils/feedback.ts 里的 toastError 方法禁止在业务代码里写 console.error代码检索确认加载态必须有兜底列表类组件必须包含 loading、empty、error 三个状态的 UI手工勾选检查清单翻译成动作指令后Agent 的执行力会有一个质的提升。关键在于验收判断那一列——每一条指令都应该能对应到一个明确的检查动作要么是脚本可以自动完成的要么是代码评审时一眼能看出来的。如果一条规范翻译完之后无法对应任何可检查的信号那说明它还不够具体需要继续拆。3.3 第三步搭建 Skill 目录并编写 SKILL.md做完翻译就可以动手搭目录了。还是用前端的例子我在项目 .team-skills 目录下建了 frontend-vue-component 这块技能配套的还有 frontend-commit-message、frontend-review-checklist 两个技能。这里先展示 SKILL.md 的骨架--- name: frontend-vue-component description: 按团队规范开发或修改 Vue 组件时使用 applies_to: .vue, .tsx, .jsx --- # Vue 组件开发规范 ## 什么时候用 - 新建页面级组件或业务组件 - 修改现有组件的 props、emits、样式方案 - 重构组件拆分的颗粒度 ## 执行步骤 1. 阅读 templates/standard-component.vue以此为基底 2. 确认目录归属页面组件放 views/ 下对应路由目录业务组件放 components/ 3. 文件命名 kebab-case导出名 PascalCase 4. props 必须声明 type、default、validator需要父组件响应的一律走 emits 5. 接口请求统一走 src/api 下的封装失败时调用 feedback.ts 的 toastError 6. 列表类组件必须包含 loading、empty、error 三态 7. 完成后对照 references/component-checklist.md 逐项自查 ## 重要禁忌 - 不要直接修改 props 对象 - 不要在业务代码中直接使用 console 打日志 - 不要引入新的 UI 组件库统一走项目已有的 design system注意几个细节一是加了 frontmatter 头写清楚技能名称和适用场景这样 Agent 在任务判断时才能准确匹配二是执行步骤编号化Agent 对编号指令的跟随能力明显强于纯段落描述三是“重要禁忌”单独成节负向约束比正向引导更省 token效果也更直接。我把组件命名规范、错误处理细则这类需要查表的内容放到了 references 目录SKILL.md 里保持精简只留主流程。一个技能的主文档最好控制在 50 行以内超过这个规模就要考虑是不是拆技能了。3.4 第四步分层适配——项目级、团队级、组织级在实际推广中我很快发现只做一个项目级的 Skill 是不够的。团队里不可能只有一个项目而不同项目之间规范有共性的部分也有各自特殊的部分。全堆在一个技能里项目 A 的规范会污染项目 B。我把 Skill 分成三个层级来管理项目级.project-skills/只属于当前仓库的约定比如这个项目用了 Vue2 还是 Vue3、用的是 Element Plus 还是 Ant Design Vue、目录结构是按业务模块划分还是按技术类型划分。这类技能落地在当前项目仓库内的隐藏目录里跟着仓库走不对外分发。团队级团队共享仓库团队通用的工程规范、代码风格、组件设计约束、提交流程。这类技能放在一个独立的 team-skills 仓库里由团队成员共同维护各项目通过构建脚本拉取。组织级公共技能市场多个团队都会用到的通用规范比如安全编码规范、日志规范、数据库访问规范。这类技能通常由平台工程团队统一维护。加载顺序上组织级和团队级是基础底料项目级是定制补丁项目级技能的文件描述和指令优先级要高于团队级。这样可以处理一个实际问题团队通用规范说“全面使用 Vue 3 Composition API”但某个老项目还在用 Vue 2 Options API那么这个项目目录下的项目级技能就要明确覆盖这一条写“本项目保留 Options API 风格禁止在现有 Options API 组件中混用 Composition API”。Agent 在加载技能时项目级的指令要能压过团队级的默认约定。3.5 第五步验证效果用一个小任务试水Skill 建好之后不要直接全员推广先用一个真实任务验证。我在试点项目里给 Agent 抛了个小需求新增一个“用户详情”的弹窗组件。它需要根据接口返回渲染用户信息包含加载中和空数据状态。没有挂载 Skill 之前Agent 写出的组件是自由发挥的文件名用了 PascalCaseprops 没写 validator接口请求直接写在组件内部失败时 console.error。加上 Skill 之后同一任务的结果差异非常明显组件被正确放到了 views/user/components/ 目录文件名是 user-detail-dialog.vueprops 有完整的类型声明和 validator接口调用走了封装好的 api 函数错误处理用的统一的 toastError三态 UI 齐全。这个对比直观说明了 Skills 的价值不是让 Agent 从“不会写”变成“会写”而是从“会写”变成“写得符合团队的协作方式”。这也是我说的把“会写代码的 Agent”变成“会按规范干活的同事”的本质。4. 适配期的真实翻车清单我踩过的坑和绕坑姿势Skill 适配并不是一帆风顺的。我在几个团队推广的过程中踩了不少坑有些问题极具迷惑性不实际跑一遍根本想不到。挑几个最有代表性的说一下。4.1 坑一一个巨型 Skill 试图搞定所有前端任务第一个版本我图省事把前端所有规范全部写进了一个 frontend-developer 技能里。SKILL.md 写了三百多行包含组件开发、样式方案、状态管理、路由配置、接口请求、提交规范甚至还有代码评审清单。看起来挺全面实际用起来一塌糊涂。表现主要有两个首先上下文占据过大Agent 在处理一个简单的样式调整任务时也要加载全部三百行内容相当于让它背完整本规范再开始写一行 CSS。其次指令之间互相干扰Agent 经常在完成一个任务时“顺便”遵守了无关的规范反而干扰了主要工作。解法是拆技能。把一个大技能拆成功能内聚的小技能每个技能只负责一类场景写组件就加载组件技能提交代码就加载提交规范技能代码评审就加载审查技能。技能之间的边界越清晰Agent 的调用准确率越高。4.2 坑二全局技能和项目实际情况打架团队级技能里写了“新组件一律使用 Composition API”但某个老项目还是 Options API 风格。Agent 按团队技能干活新建的组件和周围老代码格格不入code review 被打回。这个坑的根因在于技能设计时没有考虑不同项目的语境差异。解法就是前面说的分级适配和优先级覆盖。团队级技能要主动留出可以被项目级技能覆盖的口子在文档里写明“如项目有特殊约定以项目内 .project-skills 为准”。项目级技能里遇到冲突的条目直接写明覆盖逻辑和原因。Agent 加载冲突时不会凌乱因为它有明确的优先级规则。4.3 坑三写了没法验证的规则还有一个很典型的坑Skill 里写了一堆“高质量”“优雅”“合理”这类主观形容词比如“代码要优雅”“异常处理要合理”。这些话模型无法精确执行因为“优雅”和“合理”没有明确的判断标准。结果就是 Agent 看似遵守了实际上没有任何改变该被评审打回的照样打回。后来我给自己定了一条规矩每条 Skill 里的指令都必须能对应到一个可检查的信号。要么是自动化的脚本、代码检索、正则匹配要么是人工 review 时一眼能看出来的明确条件。写不出验收标准的指令一开始就不应该写进去。4.4 坑四规范更新了Skill 没跟着同步团队规范是动态变化的。某个季度组件库从 2.x 升级到了 3.xAPI 有破坏性变更。人在团队里通过公告和代码评审逐渐接受了新用法但 Skill 里写的还是旧 API。Agent 以后的代码越写越“过时”。这个坑不能靠自觉来防要靠机制。我现在的做法是把规范文档和 Skill 放进同一个仓库同一套变更流程团队规范文档的 MR 必须连带更新对应的 Skill 文件由同一个 reviewer 把关。如果 Skill 没法随规范同步更新那就干脆先不建这条 Skill。4.5 坑五上下文预算失控技能加载过多技能拆得太细也有副作用。一次任务里Agent 可能同时匹配到组件开发、样式方案、接口请求、提交规范等多个技能。如果每个技能都加载主文档和全部参考资料上下文很快就满了反而没空间思考业务逻辑。我采取两个控制手段一是技能文档瘦身SKILL.md 控制在 30 到 60 行参考资料里的内容让 Agent 按需打开不由主文档一次性拉取二是在 description 字段里写清楚触发条件越精确越好。比如“仅在新建组件或修改 props 时使用”这样无关任务就不会误触发这个技能。上下文是 Agent 最宝贵的资源技能加载和它是一笔账每一块上下文都要花在刀刃上。5. 从一个人适配到全项目铺开Skills 仓库的运营与迭代当你在一个项目里把 Skills 跑通之后接下来的问题就变成了怎么让整个团队都用起来并且持续维护让这些技能不腐烂。5.1 把 Skills 当代码工程来管理而不是文档收集Skills 最容易被当成“写给大家看的文档”但实际上它应该被当成代码来管理。我的做法是在团队内部建了一个 team-skills 仓库目录结构按技能用途分好每个 MR 必须经过评审合并有版本发布有变更记录。评审 skill 的 MR 和评审普通代码 MR 看的东西不一样。我看三点指令是否能被 Agent 稳定执行有没有含糊的主观描述技能之间是否有冲突有没有重复覆盖的领域上下文消耗是否合理能否再瘦身。三个维度都过关才会合进去。5.2 用“技能质量评分卡”来衡量 Skill 的优劣技能维护最怕的是“建了没人管后来没人用”。我给团队设计了一个简单的评分卡每个季度审视一轮。评分的维度不复杂但很实用维度衡量方式合格线触发准确率Agent 加载该技能的任务中确实需要它的比例 80%扰动率加载该技能的任务输出被 review 打回的比例低于不加载时文档新鲜度Skill 内的指令和当前团队规范是否一致无过时条目上下文效率技能平均加载体量 / 有效指令比例主文档 60 行被判定为长期无人触发或者反而拉低效率的技能我会直接下架。技能不是越多越好维护一个“少而精”的技能库比堆一大仓库没人用的死技能健康得多。5.3 和 CI 流水线分工能自动挡的不要靠技能手挡Skills 不能替代工程基础设施。我的切分原则是凡是 CI 可以自动检查的规范一律交给 CISkills 里只需要提示 Agent 执行对应的脚本并处理结果。只有那些必须靠理解任务结构才能做对的决策才需要写进 Skills 引导 Agent 判断。举个例子提交信息的格式。我在 Git 的 commit-msg 钩子里已经做了一整套校验不符合规范直接拦截。Skill 要做的事情不是把规范写一遍而是告诉 Agent“提交前要阅读提交信息规范并按照规范填写CI 会校验”。这样 Skill 就不需要把每一种提交类型都列出来反而省下上下文。5.4 用数据说话适配前后到底改变了什么团队最关心的一个问题做了 Skills 适配Agent 产出的代码质量到底提升了多少反正我是不信“感觉好多了”这种话的数据才是硬道理。我在试点项目统计了三个月的 MR 数据适配前Agent 产出的 PR 平均要经过 2.7 轮 review 才能合入其中一半的修改集中在错误处理、命名风格和提交信息这类规范问题上适配后平均 review 轮次降到了 1.2 轮规范类修改占返工内容的比例明显下降reviewer 终于可以把精力放在架构设计、边界条件和性能优化上而不是反复纠正格式和风格。还有另一个更易被忽视的价值新人上手时间。“按团队规范干活”这件事人类新人通常要一两个月才能完全形成肌肉记忆。把同样的规则打包成 Skill 传给新人和 Agent 后新人第一次写出符合所有团队规范的代码所需的时间少了很多因为 Rules 是显式写出来的他看一眼就能通晓全局不用自己慢慢从 Review 教训里悟了。5.5 逐步推开的路径别想着一口气吃成胖子如果你准备在团队里推 Skills我的建议是从一条最痛、最容易验证的规范开始。比如提交信息规范或者组件目录规范先做成第一个 Skill 项目让 Agent 在一类任务上明显变合规。验证有效之后再逐步扩展不要一上来就做一个覆盖所有规范的大工程。另外想强调一点Skills 是团队知识资产的一部分它的价值在于持续迭代。今天写的 Skill半年后可能因为技术栈升级、架构调整而失效。把它当代码管当成一个活的项目运营而不是当成一份定稿的文档扔在仓库里这个认知比任何具体技巧都重要。在我自己的项目里现在 Agent 已经能独立承担不少日常开发工作产出的代码在规范契合度上基本和团队里工作了一两年的工程师一个水平。这个过程不复杂但需要耐心先把规范翻译成动作再让动作变得可验证最后把它运作成一个持续更新的体系。这套方法论我认为不止适用于前端任何有明确工程规范、又想让 Agent 深度参与开发的团队都可以参考着做一遍。