隊(duì)：Skills機(jī)制與代碼規(guī)范實(shí)戰(zhàn)指南)
最近團(tuán)隊(duì)里開始大規(guī)模用 AI 編程 Agent 寫代碼大家吐槽最多的反而不是“它不會寫代碼”而是“寫出來的東西一股 AI 味”命名風(fēng)格東一榔頭西一棒子、依賴隨手亂加、Git 提交信息寫得像機(jī)翻、明明團(tuán)隊(duì)內(nèi)有統(tǒng)一的技術(shù)棧和約定它偏要用自己訓(xùn)練數(shù)據(jù)里的那套來。說白了一個會寫代碼的 Agent 和一名能直接加入項(xiàng)目干活的同事之間差的不是代碼能力而是對團(tuán)隊(duì)規(guī)范的理解和遵守。Skills 機(jī)制就是補(bǔ)上這段差距的關(guān)鍵。它相當(dāng)于給 Agent 預(yù)置了一套“崗位手冊”把你們項(xiàng)目里的代碼規(guī)范、提交規(guī)范、架構(gòu)約定、常用方案全部轉(zhuǎn)換成 Agent 能讀取、能執(zhí)行的操作規(guī)程。這篇文章我會從實(shí)戰(zhàn)角度拆解怎么把 Skills 用起來讓 Agent 從“會寫代碼的工具”變成“按規(guī)范干活的同事”。1. 先搞清楚 Skills 到底解決了什么問題1.1 通用 Agent 的“能力幻覺”和“規(guī)范盲區(qū)”很多人第一次用 Claude Code、Codex 這類工具時會覺得它“什么都會”。但實(shí)際上它會的只是“寫代碼”這個泛化能力對你們團(tuán)隊(duì)的具體約定一無所知。舉個最常見的例子團(tuán)隊(duì)后端統(tǒng)一用 Java 17 Spring Boot接口返回結(jié)構(gòu)固定是{ code, message, data }可你讓 Agent 生成一個查詢接口它很可能會按照自己訓(xùn)練語料里最常見的寫法給你返回一個直接丟實(shí)體類的結(jié)構(gòu)甚至用上 Java 8 的LocalDate處理邏輯和團(tuán)隊(duì)里的工具類完全脫節(jié)。再比如前端團(tuán)隊(duì)已經(jīng)定了用 Vue 3 TypeScript unplugin-auto-import組件里不允許手動import { ref } from vue。但通用 Agent 生成的代碼大概率會把這些 import 全部寫上你還要花時間一行行刪。這些小問題疊加起來寫代碼的時間是省了Review 的時間反而變長了。Skills 解決的就是這種“規(guī)范盲區(qū)”。它的核心思路不是教 Agent 更多編程知識而是把你們項(xiàng)目里那些“默認(rèn)大家都該知道”的事情顯式地寫給 Agent 看。1.2 Skills、Prompt 和 Rules 三者的邊界剛開始接觸 Skills 的人容易把它和普通的 Prompt 指令、Rules 規(guī)則混淆。我自己的理解是這樣Prompt 是一次性的對話上下文告訴 Agent“這一次任務(wù)怎么干”不持久換個會話就失效。Rules 是全局的行為約束相當(dāng)于公司的“員工手冊”規(guī)定哪些能做、哪些不能做通常放在項(xiàng)目根目錄的規(guī)則文件里每個會話都會加載但它偏“禁止性條款”不適合承載太長的操作細(xì)節(jié)。Skills 是可復(fù)用的“崗位操作手冊”圍繞某一個具體任務(wù)封裝完整的步驟、模板、示例和腳本Agent 遇到相關(guān)任務(wù)時再動態(tài)調(diào)用相當(dāng)于“遇到這種情況按這個流程走”。用團(tuán)隊(duì)來類比Rules 是“上班不能遲到、代碼必須過 Lint”Prompt 是“今天把登錄模塊改一下”Skills 則是“新同事入職后給他一份怎么提 PR、怎么寫 commit message、怎么跑測試的標(biāo)準(zhǔn)化流程文檔”。三者配合Agent 才算真正融入團(tuán)隊(duì)。2. 項(xiàng)目級 Skills 適配的整體設(shè)計(jì)思路2.1 先盤點(diǎn)團(tuán)隊(duì)里有哪些“隱性規(guī)范”做 Skills 適配的第一步不是急著寫文件而是先盤點(diǎn)。我建議把團(tuán)隊(duì)里大家約定俗成、但從未寫進(jìn)文檔的規(guī)范都列出來至少包括這些維度代碼風(fēng)格縮進(jìn)、命名、注釋語言、是否強(qiáng)制類型標(biāo)注、Lint 規(guī)則。技術(shù)棧約束規(guī)定使用的框架版本、UI 庫、HTTP 客戶端、序列化方式、數(shù)據(jù)庫訪問層。架構(gòu)模式分層方式、目錄結(jié)構(gòu)、依賴注入風(fēng)格、異常處理策略。工程流程Git 分支命名、commit message 格式、PR 描述模板、測試要求、構(gòu)建命令。業(yè)務(wù)約定接口返回結(jié)構(gòu)、錯誤碼規(guī)范、日志格式、敏感信息脫敏要求。有一個很實(shí)用的做法找團(tuán)隊(duì)里代碼 Review 最嚴(yán)格的那個同事問問他平時都會挑出哪些問題。我當(dāng)初做適配的時候就是從幾個“Review 狠人”的評論里提取出高頻意見然后逐個轉(zhuǎn)成 Skills。這樣出來的適配目錄基本就是團(tuán)隊(duì)真實(shí)痛點(diǎn)的映射。2.2 確定 Skills 的目錄和命名規(guī)范目前各家 Agent 對 Skills 的目錄約定不完全一致但主流形式大同小異通常是在項(xiàng)目根目錄創(chuàng)建一個skills文件夾有的工具是.claude/skills有的是./skills每個 Skill 一個子目錄。我建議命名全部用小寫字母加連字符例如backend-api-handler、git-commit-convention、vue3-component-style。每一個 Skill 目錄下必須有SKILL.md文件這是 Agent 讀取的核心入口。其他輔助資源可以包括模板文件、示例代碼、可執(zhí)行的校驗(yàn)?zāi)_本等。這里有一個關(guān)鍵點(diǎn)目錄名要能體現(xiàn)“場景”而不是“知識點(diǎn)”。比如python-coding-style就太泛了Agent 不知道該什么時候用它改成python-backend-api-implementation就更明確——當(dāng)需要寫 Python 后端接口時使用。Skills 的一個重要特性就是按需加載描述越精確Agent 判斷“該不該用”的準(zhǔn)確率越高。2.3 分層適配團(tuán)隊(duì)級、項(xiàng)目級、個人級Skills 不一定都要塞在項(xiàng)目里。我實(shí)際工作中是分三層的團(tuán)隊(duì)級 Skills放在一個獨(dú)立的 Git 倉庫里統(tǒng)一管理項(xiàng)目通過 submodule 或復(fù)制方式引入。這類 Skills 包含團(tuán)隊(duì)的通用規(guī)范比如 Git 提交規(guī)范、代碼 Review 檢查清單。項(xiàng)目級 Skills放在具體項(xiàng)目倉庫里包含和這個項(xiàng)目強(qiáng)相關(guān)的模式比如“這個項(xiàng)目特有的分頁返回結(jié)構(gòu)”、“用戶權(quán)限校驗(yàn)的寫法”。個人級 Skills放在你的用戶目錄下是個人偏好比如你習(xí)慣用什么測試框架寫單測、喜歡在代碼里加什么注釋風(fēng)格。分層的好處是避免把團(tuán)隊(duì)規(guī)范復(fù)制到幾十個倉庫里改一處其他不同步。我當(dāng)前的做法是團(tuán)隊(duì)級和項(xiàng)目級分開維護(hù)個人級基本不用因?yàn)榧热皇窍Ｍ?Agent “按團(tuán)隊(duì)規(guī)范干活”個人偏好最好別混進(jìn)來否則輸出又變得不穩(wěn)定。3. SKILL.md 寫作要點(diǎn)把規(guī)范翻譯給 Agent 聽3.1 SKILL.md 的標(biāo)準(zhǔn)結(jié)構(gòu)一個能被 Agent 準(zhǔn)確理解的 SKILL.md我一般按下面的結(jié)構(gòu)來寫--- name: backend-api-implementation description: 當(dāng)需要實(shí)現(xiàn)一個后端 HTTP API 接口時使用包括 Controller、Service、Mapper 的代碼生成和異常處理。不要在處理非接口任務(wù)時使用。 --- # 后端 API 接口實(shí)現(xiàn)規(guī)范 ## 適用場景 - 新增一個 RESTful 接口 - 修改已有接口的返回結(jié)構(gòu) ## 技術(shù)棧與依賴 - 使用 Spring Boot 3.xJava 17 - HTTP 響應(yīng)統(tǒng)一為 ResponseResultT禁止直接返回實(shí)體類 ## 實(shí)現(xiàn)步驟 1. 先閱讀 src/main/resources/api-schema.yaml 中的接口定義 2. 在 controller 包下新建類... 3. ... ## 驗(yàn)收清單 - [ ] 所有接口都有 Validated 參數(shù)校驗(yàn) - [ ] 使用項(xiàng)目內(nèi)的 BizException 拋出業(yè)務(wù)異常 - [ ] 新依賴有正當(dāng)理由并更新 dependencies.md ## 示例代碼 參考 examples/user-controller.example.java注意YAML frontmatter 里的name和description是 Agent 判斷是否加載這個 Skill 的重要依據(jù)可以寫得詳細(xì)但不要講廢話。特別是 description 里要寫清楚“什么時候不該用”這能明顯減少誤觸發(fā)。3.2 用“驗(yàn)收清單”代替“講道理”我踩過最大的坑就是在 SKILL.md 里試圖給 Agent“講道理”——“代碼應(yīng)當(dāng)具有良好的可讀性”、“注意邊界情況”。這種大而化之的話對 Agent 約等于沒說它不知道你的“可讀性”具體指什么。后來我把所有規(guī)范全改成可以打勾的驗(yàn)收項(xiàng)。比如“具有良好的可讀性”改成方法長度不超過 80 行超過時拆分禁止使用魔法數(shù)字常量統(tǒng)一放在Constants.java不允許出現(xiàn)邏輯與超過兩層的嵌套條件如有需要提前 return這種清單式寫法有兩個好處一是 Agent 能在完成代碼后自行對照檢查二是你在 Review 時拿同一份清單去核對人機(jī)標(biāo)準(zhǔn)一致扯皮概率大幅下降。3.3 在 SKILL.md 里嵌入“反面示例”只有正面示例是不夠的。Agent 很擅長模仿格式但容易忽略哪些寫法是被禁止的。我建議每個 Skill 里都加一個“反面示例”小節(jié)展示團(tuán)隊(duì)代碼里經(jīng)常出現(xiàn)的壞味道并寫明為什么不推薦。舉一個實(shí)際的例子我們的前端 Skill 里有這么一段## 反面示例 ? 在組件里手動導(dǎo)入 Vue API ts import { ref, computed } from vue? 正確做法項(xiàng)目已配置 unplugin-auto-import直接使用ref和computed即可。這個技巧的效果非常明顯。Agent 生成代碼時只要在上下文里看到反面示例就很少再踩同一個坑。我甚至覺得反面示例比正面示例更值得寫因?yàn)榇蟛糠?Agent 的“基礎(chǔ)編碼能力”已經(jīng)不錯了缺的是對團(tuán)隊(duì)禁忌的了解。 ## 4. 實(shí)操把高頻場景做成 Skills 套件 ### 4.1 場景一Git 提交規(guī)范適配 Git 提交信息是 Agent 最容易“放飛自我”的地方。我見過它提交 “update code” 這種毫無信息量的信息也見過它寫一整段英文散文。后來我寫了一個 git-commit-convention Skill內(nèi)容很簡短 markdown --- name: git-commit-convention description: 在生成 Git commit message 時使用。團(tuán)隊(duì)采用 Conventional Commits 規(guī)范。 --- # 團(tuán)隊(duì) Git 提交規(guī)范 - 格式type(scope): subject - type 使用feat / fix / docs / style / refactor / test / chore - scope 使用模塊名例如feat(user-service): 增加用戶注銷接口 - subject 用中文描述不要用句號結(jié)尾不超過 50 個字 - 禁止使用 “update”、“modify” 這類無意義動詞這個 Skill 很短但價值很高。它配合 Agent 工具的auto-commit功能基本能保證每一條提交信息都符合團(tuán)隊(duì)規(guī)范。寫這類 Skill 的秘訣就是只列規(guī)則不要長篇解釋Agent 提取規(guī)則的能力很強(qiáng)反而是大段文字會稀釋重點(diǎn)。4.2 場景二后端接口代碼規(guī)范適配如果你們團(tuán)隊(duì)有比較嚴(yán)重的接口風(fēng)格不統(tǒng)一問題可以寫一個backend-api-implementationSkill。這個 Skill 通常是最復(fù)雜的因?yàn)樗晚?xiàng)目的具體技術(shù)棧綁定。我在工程里是這樣組織的目錄結(jié)構(gòu)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 重點(diǎn)寫三部分接口處理流程、統(tǒng)一響應(yīng)結(jié)構(gòu)、異常處理規(guī)則。模板和示例代碼則給出骨架和標(biāo)準(zhǔn)寫法。這樣 Agent 生成時相當(dāng)于“照著模板填業(yè)務(wù)”生成結(jié)果非常穩(wěn)定。整個團(tuán)隊(duì)收益最大的地方在于以前不同人寫出來的接口參數(shù)校驗(yàn)有的用Validated有的手寫 if異常有的拋BizException有的直接返回 null現(xiàn)在所有 Agent 生成的接口都是同一套結(jié)構(gòu)Review 成本直線下降。4.3 場景三前端組件開發(fā)適配我還寫過一個vue3-component-implementationSkill解決的是組件庫使用不規(guī)范的問題。我們的項(xiàng)目引入了 element-plus但團(tuán)隊(duì)內(nèi)部又封裝了一些通用組件比如ProTable、ProDialog有些 Agent 不知道這些封裝的存在直接去用原生 table 和 dialog 拼。Skill 里我寫明了優(yōu)先使用團(tuán)隊(duì)封裝的 Pro 組件不直接使用 element-plus 原生組件實(shí)現(xiàn)表格和彈窗組件樣式統(tǒng)一使用 scoped CSS 變量不用!important通用狀態(tài)用 Pinia不要用組件間事件總線所有表單必須有rules校驗(yàn)校驗(yàn)規(guī)則集中在validate.ts寫這個 Skill 時最好附帶 Pro 組件的 props 說明文檔和最小示例。Agent 有了參考文檔后生成的組件代碼基本可以直接用不再需要你一遍遍提醒“用 ProTable 啊”。4.4 場景四數(shù)據(jù)庫訪問層規(guī)范適配數(shù)據(jù)訪問層的規(guī)范通常和具體 ORM 綁定。比如我們團(tuán)隊(duì)禁止在 Mapper XML 里寫復(fù)雜的動態(tài) SQL復(fù)雜查詢必須走 QueryWrapper 或者在 Service 層用 Java 代碼處理。這個規(guī)則如果不寫進(jìn) SkillAgent 很容易生成一長串if標(biāo)簽的 SQL維護(hù)起來非常痛苦。數(shù)據(jù)庫訪問層 Skill 里我還會寫明表和實(shí)體類的命名規(guī)則、字段類型映射約定、邏輯刪除字段的處理方式。這類規(guī)范如果在代碼 Review 時逐條講給 Agent 聽效率太低寫成 Skill 一次配置后面所有會話都能穩(wěn)定生效。5. 把 Skills 接入日常工作流的幾種方式5.1 最簡單的方式項(xiàng)目根目錄加說明對于 Claude Code 這類工具官方支持自動發(fā)現(xiàn)項(xiàng)目里的skills目錄。其他 Agent 工具也大多支持類似的機(jī)制。你在項(xiàng)目根目錄放好 Skills 目錄之后新建會話時 Agent 就會先掃描可用的 Skills然后在對話中根據(jù)用戶請求自動匹配。用起來之后你會發(fā)現(xiàn)Agent 在響應(yīng)任務(wù)前有時會主動說一句“我會參考項(xiàng)目里的 xxx Skill”。如果沒看到這句話而你確定當(dāng)前任務(wù)應(yīng)該匹配某個 Skill可能就是因?yàn)?description 寫得不夠精確或者目錄沒放對位置。5.2 把 Skills 和 Rules 串起來用Rules 通常只適合寫一些全局性的、不依賴具體場景的硬約束比如“禁止將敏感配置硬編碼在代碼里”“所有對外接口必須記錄日志”。具體到某個場景怎么做再扔給對應(yīng)的 Skill。我的經(jīng)驗(yàn)是Rules 里寫“不做什么”SKILL.md 里寫“應(yīng)該怎么做”。兩者配合最大的好處是Agent 先通過 Rules 守住底線再通過 Skills 把活干到符合團(tuán)隊(duì)的期望效果比只用一種好很多。5.3 用腳本自動校驗(yàn) Skills 是否生效Skills 不生效是常見問題單純靠聊天確認(rèn)不夠。我在工程里加了一個很輕量的 Node 腳本每次 Agent 生成完代碼后會自動執(zhí)行項(xiàng)目已有的 lint 和測試。前端跑 eslint vue-tsc后端跑 mvn test。只要有一項(xiàng)不過就要求 Agent 必須修復(fù)到通過為止。這個機(jī)制雖然不復(fù)雜但能倒逼 Agent 認(rèn)真讀取 Skill 里寫的內(nèi)容。尤其當(dāng)我在 SKILL.md 里寫了“代碼必須通過以下命令校驗(yàn)”之后Agent 會在生成時主動檢查自己有沒有違反規(guī)范出錯率驟降。5.4 不同 Agent 工具間的通用化我知道很多團(tuán)隊(duì)不止用一種 Agent 工具有人用 Claude Code有人用 Codex還有人用 Cursor。好消息是 Skills 的理念已經(jīng)非常通用很多工具都支持只是加載方式略有差異。我的做法是維護(hù)一份標(biāo)準(zhǔn)的skills目錄然后在不同工具里做適配。比如 Cursor 圈定規(guī)則的方式是.cursor/rules我可以在里面寫一個很瘦的規(guī)則文件內(nèi)容只有一句“遇到前端組件開發(fā)任務(wù)時閱讀skills/vue3-component-implementation/SKILL.md”。這樣不同的工具最終都指向同一份權(quán)威文檔避免各搞一套導(dǎo)致口徑不一致。6. 常見問題與排查技巧實(shí)錄6.1 Skills 完全沒被觸發(fā)這是我被問得最多的問題。經(jīng)過排查大部分情況出在 description 寫得不夠具體Agent 判斷不了當(dāng)前任務(wù)屬于哪個 Skill。比如我有一個 Skill 的 description 寫的是“處理前端相關(guān)任務(wù)”結(jié)果 Agent 幾乎從不加載它因?yàn)椤扒岸讼嚓P(guān)”太寬泛了連 Agent 自己都不知道什么時候該用。后來我把 description 改成“當(dāng)需要實(shí)現(xiàn)或修改 Vue 3 組件時使用包括新增頁面組件、通用組件不適用于樣式調(diào)整、工具函數(shù)編寫”觸發(fā)率就正常了。另外還要確認(rèn) Skill 目錄有沒有被正確掃描有些工具要求skills目錄放在項(xiàng)目根目錄有些則需要在配置文件中顯式聲明路徑這一步很容易被忽略。還有一個細(xì)節(jié)如果你某個 Skill 加了 external 依賴或者引用了本地腳本要確保這些資源路徑是相對目錄寫的不要用絕對路徑。否則復(fù)制到別的機(jī)器上就會因?yàn)槁窂绞?dǎo)致 Skill 加載失敗。6.2 SKILL.md 太長導(dǎo)致 Agent 執(zhí)行到一半“失憶”剛開始我把 SKILL.md 寫成了一篇幾千字的百科全書想覆蓋所有情況結(jié)果 Agent 在處理任務(wù)時上下文被大量擠占反而忽略了關(guān)鍵步驟。后來我學(xué)乖了每個 SKILL.md 盡量控制在 200 行以內(nèi)只保留必須的步驟和驗(yàn)收項(xiàng)那些更細(xì)節(jié)的內(nèi)容放到同目錄下的參考文檔里需要時再讓 Agent 讀取。你可以把 SKILL.md 理解成一個目錄索引它告訴 Agent “先去讀哪個文件、按照什么順序操作”而不是把所有信息都塞進(jìn)去。這個調(diào)整之后Agent 的執(zhí)行穩(wěn)定度提升非常明顯。6.3 多個 Skills 之間產(chǎn)生沖突當(dāng)項(xiàng)目里的 Skills 數(shù)量變多以后沖突是難免的。比如一個backend-api-implementation里要求所有接口使用POST方法另一個restful-api-design里又說查詢接口應(yīng)該用GET。Agent 同時加載兩個 Skill 時就會左右為難生成結(jié)果隨機(jī)性很大。我處理沖突的原則是每個場景只設(shè)置一個唯一權(quán)威的 Skill其他 Skill 引用它而不是重復(fù)定義。如果確實(shí)需要例外就在對應(yīng)的 SKILL.md 里顯式寫“本規(guī)范優(yōu)先于 xxx Skill”。這種“唯一權(quán)威”的策略能讓 Agent 在做判斷時有明確的優(yōu)先級依據(jù)不會出現(xiàn)兩套標(biāo)準(zhǔn)打架的情況。6.4 生成的代碼仍然不完全符合預(yù)期Skills 能大幅提升一致性但不可能保證 100% 符合預(yù)期。遇到這種情況我的處理方法是先把部分正確的結(jié)果收下然后針對具體的偏差補(bǔ)充 SKILL.md 里的示例或驗(yàn)收清單下一次生成就會好很多。這其實(shí)是一個持續(xù)迭代的過程Skills 的質(zhì)量是在一次次 Review 中越磨越好的。另外一個容易被忽略的點(diǎn)是任何 SKILL.md 里寫的指令都要確保 Agent 有足夠的工具和權(quán)限去執(zhí)行。比如你要求它跑測試但它所在的執(zhí)行環(huán)境沒有安裝測試依賴那這個驗(yàn)收項(xiàng)永遠(yuǎn)過不了。所以 Skill 里的每一個操作步驟都必須在真實(shí)環(huán)境里手動跑一遍驗(yàn)證。7. 關(guān)于 Skills 適配我最后的幾點(diǎn)個人體會做 Skills 適配這件事最難的其實(shí)不是技術(shù)而是梳理出團(tuán)隊(duì)“真正在用的規(guī)范”。很多規(guī)范連團(tuán)隊(duì)成員自己都沒意識到比如代碼風(fēng)格、命名習(xí)慣、模塊劃分邏輯它們分散在不同的代碼和 Review 記錄里。把這一層隱性知識顯性化無論對 Agent 還是對新入職的同事都是巨大的效率提升。我也建議別想著一口氣把所有場景都適配完。先挑兩三個最高頻、最痛的點(diǎn)比如 Git 提交規(guī)范和接口代碼規(guī)范做出效果給團(tuán)隊(duì)看然后慢慢擴(kuò)展。搞得太重太全一方面維護(hù)成本高另一方面 Agent 加載時也會犯選擇困難癥。最后一個小技巧每次讓 Agent 干活時可以在對話里顯式提一句“先參考項(xiàng)目里的 xxx Skill”。這個動作能幫你快速驗(yàn)證 Skill 是否能被正確觸發(fā)同時也能給 Agent 一個明確的行為錨點(diǎn)。用久了你會發(fā)現(xiàn)Agent 不再像是“一個外部的生成器”而更像一個熟悉你們項(xiàng)目、知道分寸感的協(xié)作者。 AI編程Agent融入團(tuán)隊(duì)：Skills機(jī)制與代碼規(guī)范實(shí)戰(zhàn)指南
最近團(tuán)隊(duì)里開始大規(guī)模用 AI 編程 Agent 寫代碼大家吐槽最多的反而不是“它不會寫代碼”而是“寫出來的東西一股 AI 味”命名風(fēng)格東一榔頭西一棒子、依賴隨手亂加、Git 提交信息寫得像機(jī)翻、明明團(tuán)隊(duì)內(nèi)有統(tǒng)一的技術(shù)棧和約定它偏要用自己訓(xùn)練數(shù)據(jù)里的那套來。說白了一個會寫代碼的 Agent 和一名能直接加入項(xiàng)目干活的同事之間差的不是代碼能力而是對團(tuán)隊(duì)規(guī)范的理解和遵守。Skills 機(jī)制就是補(bǔ)上這段差距的關(guān)鍵。它相當(dāng)于給 Agent 預(yù)置了一套“崗位手冊”把你們項(xiàng)目里的代碼規(guī)范、提交規(guī)范、架構(gòu)約定、常用方案全部轉(zhuǎn)換成 Agent 能讀取、能執(zhí)行的操作規(guī)程。這篇文章我會從實(shí)戰(zhàn)角度拆解怎么把 Skills 用起來讓 Agent 從“會寫代碼的工具”變成“按規(guī)范干活的同事”。1. 先搞清楚 Skills 到底解決了什么問題1.1 通用 Agent 的“能力幻覺”和“規(guī)范盲區(qū)”很多人第一次用 Claude Code、Codex 這類工具時會覺得它“什么都會”。但實(shí)際上它會的只是“寫代碼”這個泛化能力對你們團(tuán)隊(duì)的具體約定一無所知。舉個最常見的例子團(tuán)隊(duì)后端統(tǒng)一用 Java 17 Spring Boot接口返回結(jié)構(gòu)固定是{ code, message, data }可你讓 Agent 生成一個查詢接口它很可能會按照自己訓(xùn)練語料里最常見的寫法給你返回一個直接丟實(shí)體類的結(jié)構(gòu)甚至用上 Java 8 的LocalDate處理邏輯和團(tuán)隊(duì)里的工具類完全脫節(jié)。再比如前端團(tuán)隊(duì)已經(jīng)定了用 Vue 3 TypeScript unplugin-auto-import組件里不允許手動import { ref } from vue。但通用 Agent 生成的代碼大概率會把這些 import 全部寫上你還要花時間一行行刪。這些小問題疊加起來寫代碼的時間是省了Review 的時間反而變長了。Skills 解決的就是這種“規(guī)范盲區(qū)”。它的核心思路不是教 Agent 更多編程知識而是把你們項(xiàng)目里那些“默認(rèn)大家都該知道”的事情顯式地寫給 Agent 看。1.2 Skills、Prompt 和 Rules 三者的邊界剛開始接觸 Skills 的人容易把它和普通的 Prompt 指令、Rules 規(guī)則混淆。我自己的理解是這樣Prompt 是一次性的對話上下文告訴 Agent“這一次任務(wù)怎么干”不持久換個會話就失效。Rules 是全局的行為約束相當(dāng)于公司的“員工手冊”規(guī)定哪些能做、哪些不能做通常放在項(xiàng)目根目錄的規(guī)則文件里每個會話都會加載但它偏“禁止性條款”不適合承載太長的操作細(xì)節(jié)。Skills 是可復(fù)用的“崗位操作手冊”圍繞某一個具體任務(wù)封裝完整的步驟、模板、示例和腳本Agent 遇到相關(guān)任務(wù)時再動態(tài)調(diào)用相當(dāng)于“遇到這種情況按這個流程走”。用團(tuán)隊(duì)來類比Rules 是“上班不能遲到、代碼必須過 Lint”Prompt 是“今天把登錄模塊改一下”Skills 則是“新同事入職后給他一份怎么提 PR、怎么寫 commit message、怎么跑測試的標(biāo)準(zhǔn)化流程文檔”。三者配合Agent 才算真正融入團(tuán)隊(duì)。2. 項(xiàng)目級 Skills 適配的整體設(shè)計(jì)思路2.1 先盤點(diǎn)團(tuán)隊(duì)里有哪些“隱性規(guī)范”做 Skills 適配的第一步不是急著寫文件而是先盤點(diǎn)。我建議把團(tuán)隊(duì)里大家約定俗成、但從未寫進(jìn)文檔的規(guī)范都列出來至少包括這些維度代碼風(fēng)格縮進(jìn)、命名、注釋語言、是否強(qiáng)制類型標(biāo)注、Lint 規(guī)則。技術(shù)棧約束規(guī)定使用的框架版本、UI 庫、HTTP 客戶端、序列化方式、數(shù)據(jù)庫訪問層。架構(gòu)模式分層方式、目錄結(jié)構(gòu)、依賴注入風(fēng)格、異常處理策略。工程流程Git 分支命名、commit message 格式、PR 描述模板、測試要求、構(gòu)建命令。業(yè)務(wù)約定接口返回結(jié)構(gòu)、錯誤碼規(guī)范、日志格式、敏感信息脫敏要求。有一個很實(shí)用的做法找團(tuán)隊(duì)里代碼 Review 最嚴(yán)格的那個同事問問他平時都會挑出哪些問題。我當(dāng)初做適配的時候就是從幾個“Review 狠人”的評論里提取出高頻意見然后逐個轉(zhuǎn)成 Skills。這樣出來的適配目錄基本就是團(tuán)隊(duì)真實(shí)痛點(diǎn)的映射。2.2 確定 Skills 的目錄和命名規(guī)范目前各家 Agent 對 Skills 的目錄約定不完全一致但主流形式大同小異通常是在項(xiàng)目根目錄創(chuàng)建一個skills文件夾有的工具是.claude/skills有的是./skills每個 Skill 一個子目錄。我建議命名全部用小寫字母加連字符例如backend-api-handler、git-commit-convention、vue3-component-style。每一個 Skill 目錄下必須有SKILL.md文件這是 Agent 讀取的核心入口。其他輔助資源可以包括模板文件、示例代碼、可執(zhí)行的校驗(yàn)?zāi)_本等。這里有一個關(guān)鍵點(diǎn)目錄名要能體現(xiàn)“場景”而不是“知識點(diǎn)”。比如python-coding-style就太泛了Agent 不知道該什么時候用它改成python-backend-api-implementation就更明確——當(dāng)需要寫 Python 后端接口時使用。Skills 的一個重要特性就是按需加載描述越精確Agent 判斷“該不該用”的準(zhǔn)確率越高。2.3 分層適配團(tuán)隊(duì)級、項(xiàng)目級、個人級Skills 不一定都要塞在項(xiàng)目里。我實(shí)際工作中是分三層的團(tuán)隊(duì)級 Skills放在一個獨(dú)立的 Git 倉庫里統(tǒng)一管理項(xiàng)目通過 submodule 或復(fù)制方式引入。這類 Skills 包含團(tuán)隊(duì)的通用規(guī)范比如 Git 提交規(guī)范、代碼 Review 檢查清單。項(xiàng)目級 Skills放在具體項(xiàng)目倉庫里包含和這個項(xiàng)目強(qiáng)相關(guān)的模式比如“這個項(xiàng)目特有的分頁返回結(jié)構(gòu)”、“用戶權(quán)限校驗(yàn)的寫法”。個人級 Skills放在你的用戶目錄下是個人偏好比如你習(xí)慣用什么測試框架寫單測、喜歡在代碼里加什么注釋風(fēng)格。分層的好處是避免把團(tuán)隊(duì)規(guī)范復(fù)制到幾十個倉庫里改一處其他不同步。我當(dāng)前的做法是團(tuán)隊(duì)級和項(xiàng)目級分開維護(hù)個人級基本不用因?yàn)榧热皇窍Ｍ?Agent “按團(tuán)隊(duì)規(guī)范干活”個人偏好最好別混進(jìn)來否則輸出又變得不穩(wěn)定。3. SKILL.md 寫作要點(diǎn)把規(guī)范翻譯給 Agent 聽3.1 SKILL.md 的標(biāo)準(zhǔn)結(jié)構(gòu)一個能被 Agent 準(zhǔn)確理解的 SKILL.md我一般按下面的結(jié)構(gòu)來寫--- name: backend-api-implementation description: 當(dāng)需要實(shí)現(xiàn)一個后端 HTTP API 接口時使用包括 Controller、Service、Mapper 的代碼生成和異常處理。不要在處理非接口任務(wù)時使用。 --- # 后端 API 接口實(shí)現(xiàn)規(guī)范 ## 適用場景 - 新增一個 RESTful 接口 - 修改已有接口的返回結(jié)構(gòu) ## 技術(shù)棧與依賴 - 使用 Spring Boot 3.xJava 17 - HTTP 響應(yīng)統(tǒng)一為 ResponseResultT禁止直接返回實(shí)體類 ## 實(shí)現(xiàn)步驟 1. 先閱讀 src/main/resources/api-schema.yaml 中的接口定義 2. 在 controller 包下新建類... 3. ... ## 驗(yàn)收清單 - [ ] 所有接口都有 Validated 參數(shù)校驗(yàn) - [ ] 使用項(xiàng)目內(nèi)的 BizException 拋出業(yè)務(wù)異常 - [ ] 新依賴有正當(dāng)理由并更新 dependencies.md ## 示例代碼 參考 examples/user-controller.example.java注意YAML frontmatter 里的name和description是 Agent 判斷是否加載這個 Skill 的重要依據(jù)可以寫得詳細(xì)但不要講廢話。特別是 description 里要寫清楚“什么時候不該用”這能明顯減少誤觸發(fā)。3.2 用“驗(yàn)收清單”代替“講道理”我踩過最大的坑就是在 SKILL.md 里試圖給 Agent“講道理”——“代碼應(yīng)當(dāng)具有良好的可讀性”、“注意邊界情況”。這種大而化之的話對 Agent 約等于沒說它不知道你的“可讀性”具體指什么。后來我把所有規(guī)范全改成可以打勾的驗(yàn)收項(xiàng)。比如“具有良好的可讀性”改成方法長度不超過 80 行超過時拆分禁止使用魔法數(shù)字常量統(tǒng)一放在Constants.java不允許出現(xiàn)邏輯與超過兩層的嵌套條件如有需要提前 return這種清單式寫法有兩個好處一是 Agent 能在完成代碼后自行對照檢查二是你在 Review 時拿同一份清單去核對人機(jī)標(biāo)準(zhǔn)一致扯皮概率大幅下降。3.3 在 SKILL.md 里嵌入“反面示例”只有正面示例是不夠的。Agent 很擅長模仿格式但容易忽略哪些寫法是被禁止的。我建議每個 Skill 里都加一個“反面示例”小節(jié)展示團(tuán)隊(duì)代碼里經(jīng)常出現(xiàn)的壞味道并寫明為什么不推薦。舉一個實(shí)際的例子我們的前端 Skill 里有這么一段## 反面示例 ? 在組件里手動導(dǎo)入 Vue API ts import { ref, computed } from vue? 正確做法項(xiàng)目已配置 unplugin-auto-import直接使用ref和computed即可。這個技巧的效果非常明顯。Agent 生成代碼時只要在上下文里看到反面示例就很少再踩同一個坑。我甚至覺得反面示例比正面示例更值得寫因?yàn)榇蟛糠?Agent 的“基礎(chǔ)編碼能力”已經(jīng)不錯了缺的是對團(tuán)隊(duì)禁忌的了解。 ## 4. 實(shí)操把高頻場景做成 Skills 套件 ### 4.1 場景一Git 提交規(guī)范適配 Git 提交信息是 Agent 最容易“放飛自我”的地方。我見過它提交 “update code” 這種毫無信息量的信息也見過它寫一整段英文散文。后來我寫了一個 git-commit-convention Skill內(nèi)容很簡短 markdown --- name: git-commit-convention description: 在生成 Git commit message 時使用。團(tuán)隊(duì)采用 Conventional Commits 規(guī)范。 --- # 團(tuán)隊(duì) Git 提交規(guī)范 - 格式type(scope): subject - type 使用feat / fix / docs / style / refactor / test / chore - scope 使用模塊名例如feat(user-service): 增加用戶注銷接口 - subject 用中文描述不要用句號結(jié)尾不超過 50 個字 - 禁止使用 “update”、“modify” 這類無意義動詞這個 Skill 很短但價值很高。它配合 Agent 工具的auto-commit功能基本能保證每一條提交信息都符合團(tuán)隊(duì)規(guī)范。寫這類 Skill 的秘訣就是只列規(guī)則不要長篇解釋Agent 提取規(guī)則的能力很強(qiáng)反而是大段文字會稀釋重點(diǎn)。4.2 場景二后端接口代碼規(guī)范適配如果你們團(tuán)隊(duì)有比較嚴(yán)重的接口風(fēng)格不統(tǒng)一問題可以寫一個backend-api-implementationSkill。這個 Skill 通常是最復(fù)雜的因?yàn)樗晚?xiàng)目的具體技術(shù)棧綁定。我在工程里是這樣組織的目錄結(jié)構(gòu)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 重點(diǎn)寫三部分接口處理流程、統(tǒng)一響應(yīng)結(jié)構(gòu)、異常處理規(guī)則。模板和示例代碼則給出骨架和標(biāo)準(zhǔn)寫法。這樣 Agent 生成時相當(dāng)于“照著模板填業(yè)務(wù)”生成結(jié)果非常穩(wěn)定。整個團(tuán)隊(duì)收益最大的地方在于以前不同人寫出來的接口參數(shù)校驗(yàn)有的用Validated有的手寫 if異常有的拋BizException有的直接返回 null現(xiàn)在所有 Agent 生成的接口都是同一套結(jié)構(gòu)Review 成本直線下降。4.3 場景三前端組件開發(fā)適配我還寫過一個vue3-component-implementationSkill解決的是組件庫使用不規(guī)范的問題。我們的項(xiàng)目引入了 element-plus但團(tuán)隊(duì)內(nèi)部又封裝了一些通用組件比如ProTable、ProDialog有些 Agent 不知道這些封裝的存在直接去用原生 table 和 dialog 拼。Skill 里我寫明了優(yōu)先使用團(tuán)隊(duì)封裝的 Pro 組件不直接使用 element-plus 原生組件實(shí)現(xiàn)表格和彈窗組件樣式統(tǒng)一使用 scoped CSS 變量不用!important通用狀態(tài)用 Pinia不要用組件間事件總線所有表單必須有rules校驗(yàn)校驗(yàn)規(guī)則集中在validate.ts寫這個 Skill 時最好附帶 Pro 組件的 props 說明文檔和最小示例。Agent 有了參考文檔后生成的組件代碼基本可以直接用不再需要你一遍遍提醒“用 ProTable 啊”。4.4 場景四數(shù)據(jù)庫訪問層規(guī)范適配數(shù)據(jù)訪問層的規(guī)范通常和具體 ORM 綁定。比如我們團(tuán)隊(duì)禁止在 Mapper XML 里寫復(fù)雜的動態(tài) SQL復(fù)雜查詢必須走 QueryWrapper 或者在 Service 層用 Java 代碼處理。這個規(guī)則如果不寫進(jìn) SkillAgent 很容易生成一長串if標(biāo)簽的 SQL維護(hù)起來非常痛苦。數(shù)據(jù)庫訪問層 Skill 里我還會寫明表和實(shí)體類的命名規(guī)則、字段類型映射約定、邏輯刪除字段的處理方式。這類規(guī)范如果在代碼 Review 時逐條講給 Agent 聽效率太低寫成 Skill 一次配置后面所有會話都能穩(wěn)定生效。5. 把 Skills 接入日常工作流的幾種方式5.1 最簡單的方式項(xiàng)目根目錄加說明對于 Claude Code 這類工具官方支持自動發(fā)現(xiàn)項(xiàng)目里的skills目錄。其他 Agent 工具也大多支持類似的機(jī)制。你在項(xiàng)目根目錄放好 Skills 目錄之后新建會話時 Agent 就會先掃描可用的 Skills然后在對話中根據(jù)用戶請求自動匹配。用起來之后你會發(fā)現(xiàn)Agent 在響應(yīng)任務(wù)前有時會主動說一句“我會參考項(xiàng)目里的 xxx Skill”。如果沒看到這句話而你確定當(dāng)前任務(wù)應(yīng)該匹配某個 Skill可能就是因?yàn)?description 寫得不夠精確或者目錄沒放對位置。5.2 把 Skills 和 Rules 串起來用Rules 通常只適合寫一些全局性的、不依賴具體場景的硬約束比如“禁止將敏感配置硬編碼在代碼里”“所有對外接口必須記錄日志”。具體到某個場景怎么做再扔給對應(yīng)的 Skill。我的經(jīng)驗(yàn)是Rules 里寫“不做什么”SKILL.md 里寫“應(yīng)該怎么做”。兩者配合最大的好處是Agent 先通過 Rules 守住底線再通過 Skills 把活干到符合團(tuán)隊(duì)的期望效果比只用一種好很多。5.3 用腳本自動校驗(yàn) Skills 是否生效Skills 不生效是常見問題單純靠聊天確認(rèn)不夠。我在工程里加了一個很輕量的 Node 腳本每次 Agent 生成完代碼后會自動執(zhí)行項(xiàng)目已有的 lint 和測試。前端跑 eslint vue-tsc后端跑 mvn test。只要有一項(xiàng)不過就要求 Agent 必須修復(fù)到通過為止。這個機(jī)制雖然不復(fù)雜但能倒逼 Agent 認(rèn)真讀取 Skill 里寫的內(nèi)容。尤其當(dāng)我在 SKILL.md 里寫了“代碼必須通過以下命令校驗(yàn)”之后Agent 會在生成時主動檢查自己有沒有違反規(guī)范出錯率驟降。5.4 不同 Agent 工具間的通用化我知道很多團(tuán)隊(duì)不止用一種 Agent 工具有人用 Claude Code有人用 Codex還有人用 Cursor。好消息是 Skills 的理念已經(jīng)非常通用很多工具都支持只是加載方式略有差異。我的做法是維護(hù)一份標(biāo)準(zhǔn)的skills目錄然后在不同工具里做適配。比如 Cursor 圈定規(guī)則的方式是.cursor/rules我可以在里面寫一個很瘦的規(guī)則文件內(nèi)容只有一句“遇到前端組件開發(fā)任務(wù)時閱讀skills/vue3-component-implementation/SKILL.md”。這樣不同的工具最終都指向同一份權(quán)威文檔避免各搞一套導(dǎo)致口徑不一致。6. 常見問題與排查技巧實(shí)錄6.1 Skills 完全沒被觸發(fā)這是我被問得最多的問題。經(jīng)過排查大部分情況出在 description 寫得不夠具體Agent 判斷不了當(dāng)前任務(wù)屬于哪個 Skill。比如我有一個 Skill 的 description 寫的是“處理前端相關(guān)任務(wù)”結(jié)果 Agent 幾乎從不加載它因?yàn)椤扒岸讼嚓P(guān)”太寬泛了連 Agent 自己都不知道什么時候該用。后來我把 description 改成“當(dāng)需要實(shí)現(xiàn)或修改 Vue 3 組件時使用包括新增頁面組件、通用組件不適用于樣式調(diào)整、工具函數(shù)編寫”觸發(fā)率就正常了。另外還要確認(rèn) Skill 目錄有沒有被正確掃描有些工具要求skills目錄放在項(xiàng)目根目錄有些則需要在配置文件中顯式聲明路徑這一步很容易被忽略。還有一個細(xì)節(jié)如果你某個 Skill 加了 external 依賴或者引用了本地腳本要確保這些資源路徑是相對目錄寫的不要用絕對路徑。否則復(fù)制到別的機(jī)器上就會因?yàn)槁窂绞?dǎo)致 Skill 加載失敗。6.2 SKILL.md 太長導(dǎo)致 Agent 執(zhí)行到一半“失憶”剛開始我把 SKILL.md 寫成了一篇幾千字的百科全書想覆蓋所有情況結(jié)果 Agent 在處理任務(wù)時上下文被大量擠占反而忽略了關(guān)鍵步驟。后來我學(xué)乖了每個 SKILL.md 盡量控制在 200 行以內(nèi)只保留必須的步驟和驗(yàn)收項(xiàng)那些更細(xì)節(jié)的內(nèi)容放到同目錄下的參考文檔里需要時再讓 Agent 讀取。你可以把 SKILL.md 理解成一個目錄索引它告訴 Agent “先去讀哪個文件、按照什么順序操作”而不是把所有信息都塞進(jìn)去。這個調(diào)整之后Agent 的執(zhí)行穩(wěn)定度提升非常明顯。6.3 多個 Skills 之間產(chǎn)生沖突當(dāng)項(xiàng)目里的 Skills 數(shù)量變多以后沖突是難免的。比如一個backend-api-implementation里要求所有接口使用POST方法另一個restful-api-design里又說查詢接口應(yīng)該用GET。Agent 同時加載兩個 Skill 時就會左右為難生成結(jié)果隨機(jī)性很大。我處理沖突的原則是每個場景只設(shè)置一個唯一權(quán)威的 Skill其他 Skill 引用它而不是重復(fù)定義。如果確實(shí)需要例外就在對應(yīng)的 SKILL.md 里顯式寫“本規(guī)范優(yōu)先于 xxx Skill”。這種“唯一權(quán)威”的策略能讓 Agent 在做判斷時有明確的優(yōu)先級依據(jù)不會出現(xiàn)兩套標(biāo)準(zhǔn)打架的情況。6.4 生成的代碼仍然不完全符合預(yù)期Skills 能大幅提升一致性但不可能保證 100% 符合預(yù)期。遇到這種情況我的處理方法是先把部分正確的結(jié)果收下然后針對具體的偏差補(bǔ)充 SKILL.md 里的示例或驗(yàn)收清單下一次生成就會好很多。這其實(shí)是一個持續(xù)迭代的過程Skills 的質(zhì)量是在一次次 Review 中越磨越好的。另外一個容易被忽略的點(diǎn)是任何 SKILL.md 里寫的指令都要確保 Agent 有足夠的工具和權(quán)限去執(zhí)行。比如你要求它跑測試但它所在的執(zhí)行環(huán)境沒有安裝測試依賴那這個驗(yàn)收項(xiàng)永遠(yuǎn)過不了。所以 Skill 里的每一個操作步驟都必須在真實(shí)環(huán)境里手動跑一遍驗(yàn)證。7. 關(guān)于 Skills 適配我最后的幾點(diǎn)個人體會做 Skills 適配這件事最難的其實(shí)不是技術(shù)而是梳理出團(tuán)隊(duì)“真正在用的規(guī)范”。很多規(guī)范連團(tuán)隊(duì)成員自己都沒意識到比如代碼風(fēng)格、命名習(xí)慣、模塊劃分邏輯它們分散在不同的代碼和 Review 記錄里。把這一層隱性知識顯性化無論對 Agent 還是對新入職的同事都是巨大的效率提升。我也建議別想著一口氣把所有場景都適配完。先挑兩三個最高頻、最痛的點(diǎn)比如 Git 提交規(guī)范和接口代碼規(guī)范做出效果給團(tuán)隊(duì)看然后慢慢擴(kuò)展。搞得太重太全一方面維護(hù)成本高另一方面 Agent 加載時也會犯選擇困難癥。最后一個小技巧每次讓 Agent 干活時可以在對話里顯式提一句“先參考項(xiàng)目里的 xxx Skill”。這個動作能幫你快速驗(yàn)證 Skill 是否能被正確觸發(fā)同時也能給 Agent 一個明確的行為錨點(diǎn)。用久了你會發(fā)現(xiàn)Agent 不再像是“一個外部的生成器”而更像一個熟悉你們項(xiàng)目、知道分寸感的協(xié)作者。