1. 從“agent-skills”說起為什么它值得單獨(dú)拎出來聊第一次看到agent-skills這個標(biāo)題很多人會以為它只是某個倉庫里隨手放的一堆提示詞集合。但真正在 AI coding agents 這條線上折騰過一段時(shí)間的人會明白它其實(shí)指向一個更底層的問題當(dāng)模型能力越來越強(qiáng)真正拉開差距的不再是模型本身而是你喂給它的“技能包”怎么組織、怎么調(diào)用、怎么復(fù)用。agent-skills本質(zhì)上是一套圍繞 AI coding agents 構(gòu)建的技能體系通常以目錄、清單或 CLI 可識別的方式存在讓 Claude Code、VS Code 里的編碼代理、以及各種接入第三方 API 的代理工具能夠按需加載特定能力。它解決的不是“模型會不會寫代碼”而是“模型在具體項(xiàng)目里能不能穩(wěn)定地按你的規(guī)矩寫代碼”。適合誰看如果你正在用 Claude Code、正在折騰 skills CLI、或者想讓 test-driven-development 真正落到代理工作流里那這篇內(nèi)容就是寫給你的。我自己的感受是很多人裝完 Claude Code、配好 VS Code 插件、連上第三方 API 之后就以為萬事大吉結(jié)果一跑真實(shí)項(xiàng)目就發(fā)現(xiàn)代理要么亂改文件要么跳過測試要么把簡單需求做成過度設(shè)計(jì)。問題往往不在模型而在 skills 層沒有搭好。agent-skills這個標(biāo)題背后其實(shí)是一整套“讓代理從玩具變成工具”的工程化思路。2. agent-skills 的整體設(shè)計(jì)與思路拆解2.1 為什么不是“提示詞合集”而是“技能體系”早期大家用 AI coding agents習(xí)慣把一堆提示詞塞進(jìn)一個 system prompt 里或者寫一個超長的CLAUDE.md。這種做法在單次任務(wù)里還能湊合一旦項(xiàng)目變大、任務(wù)變多就會暴露三個問題提示詞互相沖突、上下文被無關(guān)內(nèi)容占滿、代理不知道什么時(shí)候該用哪條規(guī)則。agent-skills的設(shè)計(jì)思路正好相反它把能力拆成一個個獨(dú)立技能每個技能有自己的觸發(fā)條件、執(zhí)行步驟和驗(yàn)收標(biāo)準(zhǔn)。代理在運(yùn)行時(shí)根據(jù)當(dāng)前任務(wù)動態(tài)加載相關(guān)技能而不是一次性把所有規(guī)則灌進(jìn)去。這就像你帶團(tuán)隊(duì)不會讓一個人同時(shí)記住所有 SOP而是告訴他“遇到數(shù)據(jù)庫遷移就看這份文檔遇到前端組件就看那份”。這種拆法的好處很直接。第一上下文利用率高代理每次只加載當(dāng)前任務(wù)需要的技能留給代碼和推理的空間更大。第二可維護(hù)性強(qiáng)某個技能過時(shí)了改那一個文件就行不會牽一發(fā)動全身。第三可組合test-driven-development 技能可以和代碼審查技能疊加使用形成流水線。2.2 技能粒度怎么定太粗沒用太細(xì)爆炸這是我在實(shí)際搭建agent-skills時(shí)踩得最狠的一個坑。一開始我把技能切得非常細(xì)比如“寫單元測試”“運(yùn)行單元測試”“修復(fù)失敗測試”各算一個技能結(jié)果代理在任務(wù)里頻繁切換反而變得猶豫經(jīng)常在一個步驟里反復(fù)確認(rèn)。后來我調(diào)整成按“任務(wù)階段”劃分而不是按“具體動作”劃分。一個技能應(yīng)該對應(yīng)一個完整的、有明確輸入輸出的工作單元。比如test-driven-development就是一個合格粒度的技能它包含先寫測試、再寫實(shí)現(xiàn)、再跑測試、再重構(gòu)這一整條鏈路而不是拆成四個技能。判斷粒度是否合適我常用一個標(biāo)準(zhǔn)如果這個技能單獨(dú)拿出來能不能對一個真實(shí)任務(wù)產(chǎn)生可驗(yàn)證的改變能就保留不能就合并或刪掉。太粗的技能會讓代理抓不住重點(diǎn)太細(xì)的技能會讓它陷入決策疲勞。2.3 與 Claude Code、skills CLI 的協(xié)作關(guān)系agent-skills不是孤立存在的它需要宿主環(huán)境來加載和執(zhí)行。目前最常見的宿主就是 Claude Code 和各類 skills CLI。Claude Code 本身提供了代理運(yùn)行框架包括文件讀寫、終端命令執(zhí)行、上下文管理而agent-skills提供的是“在什么場景下做什么”的領(lǐng)域知識。skills CLI 的作用則更偏工具鏈它負(fù)責(zé)技能的安裝、版本管理、依賴解析和本地緩存。你可以把它理解成 npm 之于 JavaScript 項(xiàng)目的關(guān)系。沒有 CLI你也能手動把技能目錄拷來拷去但一旦技能數(shù)量上去、多人協(xié)作、需要鎖定版本CLI 就是剛需。這里有個容易被忽略的點(diǎn)技能和宿主之間的接口要穩(wěn)定。我見過有人把技能寫成強(qiáng)依賴某個 Claude Code 版本的內(nèi)部 API結(jié)果一升級就全掛。穩(wěn)妥的做法是讓技能只依賴穩(wěn)定的輸入輸出約定比如“讀取任務(wù)描述、輸出文件變更和測試結(jié)果”而不是依賴具體函數(shù)名。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 技能目錄結(jié)構(gòu)別小看文件夾命名一個可維護(hù)的agent-skills目錄通常長這樣agent-skills/ skills/ test-driven-development/ SKILL.md examples/ scripts/ code-review/ SKILL.md refactor-safely/ SKILL.md registry.json README.mdSKILL.md是核心里面寫清楚這個技能的適用場景、前置條件、執(zhí)行步驟、驗(yàn)收標(biāo)準(zhǔn)和常見錯誤。examples/放正反例代理在不確定時(shí)可以參考。scripts/放可執(zhí)行腳本比如跑測試、格式化代碼。registry.json是技能清單CLI 靠它做索引。命名上我建議用“動詞對象”或“領(lǐng)域目標(biāo)”的形式比如test-driven-development、refactor-safely。避免用utils、helpers這種模糊詞代理看到這種名字根本不知道什么時(shí)候該加載。注意技能目錄不要嵌套太深。我試過三層以上嵌套結(jié)果 CLI 掃描變慢代理加載時(shí)也容易找錯路徑。兩層足夠skills/skill-name/。3.2 SKILL.md 怎么寫才讓代理真的照做很多人寫SKILL.md像寫博客大段描述性文字代理讀完還是不知道第一步干什么。有效的寫法是結(jié)構(gòu)化指令 明確驗(yàn)收。我通常按這個模板# Skill: test-driven-development ## When to use - 任務(wù)涉及新增功能或修復(fù)缺陷 - 項(xiàng)目已有測試框架 ## Steps 1. 閱讀任務(wù)描述列出需要覆蓋的行為 2. 先寫失敗測試運(yùn)行并確認(rèn)失敗 3. 寫最小實(shí)現(xiàn)讓測試通過 4. 重構(gòu)保持測試通過 5. 輸出變更文件和測試結(jié)果 ## Acceptance - 新增測試至少覆蓋任務(wù)描述中的每個行為 - 所有測試通過 - 沒有跳過或注釋掉測試 ## Common mistakes - 先寫實(shí)現(xiàn)再補(bǔ)測試 - 測試斷言過于寬松關(guān)鍵點(diǎn)是Steps要可執(zhí)行Acceptance要可驗(yàn)證。代理最怕模糊指令比如“寫出高質(zhì)量代碼”它沒法判斷什么叫高質(zhì)量。你寫“所有測試通過且沒有跳過”它就能判斷。3.3 技能加載策略按需還是全量Claude Code 和 skills CLI 通常支持兩種加載方式全量加載和按需加載。全量加載適合技能少、任務(wù)類型單一的場景按需加載適合技能多、任務(wù)差異大的項(xiàng)目。我的經(jīng)驗(yàn)是技能超過 8 個就一定要按需加載。否則上下文里塞滿無關(guān)技能代理的注意力會被稀釋。按需加載的實(shí)現(xiàn)方式通常是在任務(wù)描述里加標(biāo)簽或者讓代理先做一次技能匹配。比如任務(wù)描述里出現(xiàn)“測試”“TDD”就加載test-driven-development出現(xiàn)“重構(gòu)”就加載refactor-safely。這里有個實(shí)操技巧給每個技能寫一句“觸發(fā)短語”放在registry.json里。代理匹配時(shí)先看觸發(fā)短語再看完整技能內(nèi)容。這樣匹配速度快準(zhǔn)確率也高。3.4 與第三方 API 和模型接入的配合現(xiàn)在很多人不只用官方模型還會通過第三方 API 接入其他模型。這時(shí)候agent-skills的寫法要更保守一些因?yàn)椴煌Ｐ蛯χ噶畹淖裱潭炔灰粯?。我?shí)測下來步驟越短、驗(yàn)收越明確跨模型穩(wěn)定性越好。具體做法是把長步驟拆成編號列表每步不超過兩句話驗(yàn)收標(biāo)準(zhǔn)用布爾判斷比如“測試通過為真否則為假”避免依賴模型自行推斷的隱含規(guī)則。如果某個技能在某個模型上表現(xiàn)差不要急著改技能先看是不是步驟太長或驗(yàn)收太模糊。提示接入第三方 API 時(shí)注意技能里不要寫死模型名稱或 API 細(xì)節(jié)。技能應(yīng)該只描述“做什么”不描述“用哪個模型做”。這樣換模型時(shí)技能不用改。4. 實(shí)操過程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 從零搭建一個最小可用 agent-skills假設(shè)你現(xiàn)在有一個項(xiàng)目想讓它支持test-driven-development技能。第一步是建目錄mkdir -p agent-skills/skills/test-driven-development touch agent-skills/skills/test-driven-development/SKILL.md touch agent-skills/registry.json然后寫registry.json{ skills: [ { name: test-driven-development, path: skills/test-driven-development, triggers: [測試, TDD, test, 單元測試] } ] }接著寫SKILL.md內(nèi)容參考上一節(jié)的模板。寫完用 skills CLI 注冊skills register ./agent-skills skills list如果skills list能看到test-driven-development說明注冊成功。然后在 Claude Code 里跑一個簡單任務(wù)比如“給這個函數(shù)加一個邊界條件測試”觀察代理是否按 TDD 步驟執(zhí)行。4.2 在 Claude Code 里驗(yàn)證技能是否生效驗(yàn)證技能生效不能只看代理說“我用了 TDD”要看它的實(shí)際行為。我通常檢查三點(diǎn)第一它有沒有先寫測試再寫實(shí)現(xiàn)第二它有沒有運(yùn)行測試并報(bào)告結(jié)果第三它有沒有在測試失敗時(shí)停下來修而不是直接改實(shí)現(xiàn)。如果代理跳過測試直接寫實(shí)現(xiàn)說明技能觸發(fā)沒生效或者SKILL.md里的步驟不夠強(qiáng)制。這時(shí)候可以在Steps里加一句“在寫任何實(shí)現(xiàn)代碼之前必須先創(chuàng)建并運(yùn)行失敗測試”。語氣要明確不要用“建議”“可以”這種軟詞。如果代理寫了測試但沒運(yùn)行檢查scripts/里有沒有提供測試命令或者SKILL.md里有沒有寫清楚運(yùn)行方式。代理不會自己猜你的測試框架你得告訴它。4.3 參數(shù)與配置測試命令、超時(shí)、重試在SKILL.md里測試命令要寫具體。比如npm test -- --runInBand不要只寫npm test因?yàn)椴煌?xiàng)目配置不一樣。超時(shí)和重試也要考慮。我一般設(shè)置單次測試超時(shí) 120 秒失敗重試 1 次。重試太多會掩蓋真實(shí)問題重試太少又容易被偶發(fā)失敗干擾。如果項(xiàng)目測試很慢可以給技能加一個“快速測試”和“完整測試”兩檔。代理在開發(fā)過程中跑快速測試提交前跑完整測試。這樣既保證反饋速度又不犧牲質(zhì)量。4.4 技能組合TDD 代碼審查 安全重構(gòu)單個技能能解決單點(diǎn)問題組合起來才能覆蓋完整工作流。我常用的組合是test-driven-development負(fù)責(zé)新增和修復(fù)code-review負(fù)責(zé)檢查變更refactor-safely負(fù)責(zé)在測試保護(hù)下重構(gòu)。組合方式有兩種一種是在任務(wù)描述里同時(shí)觸發(fā)多個技能代理按順序執(zhí)行另一種是寫一個“復(fù)合技能”把多個技能的步驟串起來。前者靈活后者穩(wěn)定。我建議先用前者等流程穩(wěn)定了再考慮后者。組合時(shí)要注意技能之間的順序。TDD 必須在重構(gòu)之前代碼審查必須在測試通過之后。如果順序錯了代理可能在不穩(wěn)定的代碼上做審查得出錯誤結(jié)論。5. 常見問題與排查技巧實(shí)錄5.1 技能不觸發(fā)先查觸發(fā)短語再查加載順序技能不觸發(fā)是最常見的問題。排查順序是第一看registry.json里的觸發(fā)短語是否覆蓋了任務(wù)描述里的關(guān)鍵詞第二看 CLI 是否真的加載了技能第三看代理的上下文里有沒有技能內(nèi)容。我遇到過一種情況觸發(fā)短語寫的是英文任務(wù)描述是中文結(jié)果匹配不上。后來我把觸發(fā)短語做成中英雙語問題就解決了。還有一種情況是技能加載順序不對后面的技能覆蓋了前面的。這時(shí)候要檢查 CLI 的加載配置確保沒有重復(fù)或沖突。5.2 代理跳過步驟用驗(yàn)收標(biāo)準(zhǔn)兜底代理跳過步驟通常是因?yàn)椴襟E不夠強(qiáng)制或者驗(yàn)收標(biāo)準(zhǔn)太寬松。解決辦法是在Acceptance里加硬性條件比如“必須提供測試運(yùn)行輸出”“必須列出變更文件”。代理為了滿足驗(yàn)收就會補(bǔ)上步驟。如果加了驗(yàn)收還是跳過可能是模型能力問題。這時(shí)候可以換一個遵循指令更好的模型或者把步驟拆得更細(xì)。我實(shí)測下來步驟從 5 步拆到 8 步跳過率會明顯下降但也不能無限拆否則代理會陷入細(xì)節(jié)。5.3 測試不穩(wěn)定區(qū)分偶發(fā)失敗和真實(shí)失敗測試不穩(wěn)定會嚴(yán)重影響代理判斷。代理看到測試失敗可能去改實(shí)現(xiàn)結(jié)果改錯了。我的做法是在技能里加一條“如果測試失敗先重跑一次如果仍然失敗再視為真實(shí)失敗”。這樣能過濾掉大部分偶發(fā)失敗。同時(shí)要檢查測試本身是否有共享狀態(tài)、時(shí)間依賴、網(wǎng)絡(luò)依賴。這些是偶發(fā)失敗的常見來源。如果測試確實(shí)不穩(wěn)定先修測試再讓代理用 TDD。否則代理會在不穩(wěn)定的基礎(chǔ)上做決策越做越亂。5.4 常見問題速查表問題可能原因排查方法解決方式技能不觸發(fā)觸發(fā)短語不匹配檢查 registry.json補(bǔ)充中英雙語觸發(fā)詞代理跳過測試步驟不強(qiáng)制查看 SKILL.md加硬性驗(yàn)收條件測試偶發(fā)失敗共享狀態(tài)/時(shí)間依賴重跑測試先修測試再啟用技能技能沖突加載順序錯誤查看 CLI 日志調(diào)整加載順序或合并技能跨模型表現(xiàn)差步驟太長對比不同模型拆短步驟明確驗(yàn)收5.5 我踩過的三個坑第一個坑是技能寫得太抽象。早期我寫“寫出優(yōu)雅的代碼”代理完全不知道怎么做。后來改成“函數(shù)不超過 30 行參數(shù)不超過 4 個”代理立刻能執(zhí)行。抽象指令對代理無效具體約束才有效。第二個坑是忽略技能版本管理。有一次我改了一個技能結(jié)果另一個項(xiàng)目也在用行為變了導(dǎo)致測試失敗。后來我給技能加版本號項(xiàng)目鎖定版本問題才解決。第三個坑是過度依賴技能。有段時(shí)間我把所有規(guī)則都塞進(jìn)技能結(jié)果代理變得死板遇到技能沒覆蓋的情況就卡住。后來我保留了一部分“自由發(fā)揮”空間讓代理在技能之外也能做合理判斷。技能是護(hù)欄不是牢籠。6. 技能體系的擴(kuò)展與長期維護(hù)6.1 從個人技能到團(tuán)隊(duì)技能庫個人用agent-skills怎么舒服怎么來。一旦團(tuán)隊(duì)用就要考慮標(biāo)準(zhǔn)化。我們團(tuán)隊(duì)的做法是技能庫放在獨(dú)立倉庫走代碼審查流程每個技能必須有負(fù)責(zé)人技能變更要通知使用方。團(tuán)隊(duì)技能庫還要解決“技能發(fā)現(xiàn)”問題。新人不知道有哪些技能可用所以我們寫了一個索引頁按任務(wù)類型分類比如“測試相關(guān)”“重構(gòu)相關(guān)”“部署相關(guān)”。每個技能一句話說明用途點(diǎn)進(jìn)去看詳情。6.2 技能質(zhì)量評估用數(shù)據(jù)說話技能好不好不能靠感覺。我們統(tǒng)計(jì)了幾個指標(biāo)技能觸發(fā)率、任務(wù)完成率、代理跳過步驟的比例、測試通過率。觸發(fā)率低說明觸發(fā)短語有問題完成率低說明步驟或驗(yàn)收有問題跳過率高說明約束不夠。這些數(shù)據(jù)不需要很復(fù)雜手動記錄幾十次任務(wù)就能看出趨勢。我建議每兩周回顧一次把表現(xiàn)差的技能挑出來優(yōu)化或下線。技能庫不是越多越好而是越精越好。6.3 與 test-driven-development 的深度綁定test-driven-development是我所有技能里用得最頻繁的一個也是收益最明顯的。它讓代理從“寫完再說”變成“先想清楚再寫”。但 TDD 技能要生效前提是項(xiàng)目有可運(yùn)行的測試框架而且測試速度不能太慢。如果項(xiàng)目沒有測試我建議先補(bǔ)最小測試集再啟用 TDD 技能。否則代理會陷入“想寫測試但沒框架”的尷尬。補(bǔ)測試不需要覆蓋所有代碼先覆蓋核心路徑就行。有了基礎(chǔ)TDD 技能才能跑起來。6.4 后續(xù)擴(kuò)展方向agent-skills的擴(kuò)展空間很大。往深了做可以加“技能依賴管理”讓技能之間聲明依賴關(guān)系CLI 自動解析。往寬了做可以加“技能市場”團(tuán)隊(duì)之間共享技能。往細(xì)了做可以給每個技能加“適用模型”標(biāo)簽不同模型加載不同技能。我目前在做的是“技能效果回放”把代理執(zhí)行技能的過程錄下來事后分析哪一步卡住、哪一步跳過。這個對優(yōu)化技能很有幫助但實(shí)現(xiàn)成本不低。如果你剛開始先把基礎(chǔ)技能跑通再考慮這些高級功能。提示技能庫要定期清理。我每季度會下線一批使用率低的技能避免維護(hù)負(fù)擔(dān)。技能不是資產(chǎn)是工具不用了就刪。7. 一些實(shí)操心得與建議如果你剛開始接觸agent-skills我的建議是從一個小技能開始不要一上來就搭大框架。先寫一個test-driven-development在真實(shí)任務(wù)里跑通感受代理的行為變化。跑通之后再考慮加第二個、第三個技能。技能寫完后一定要在真實(shí)項(xiàng)目里驗(yàn)證不要只在玩具項(xiàng)目里試。真實(shí)項(xiàng)目有歷史代碼、有依賴、有邊界條件這些才是檢驗(yàn)技能的地方。玩具項(xiàng)目里表現(xiàn)好不代表真實(shí)項(xiàng)目里能用。另外不要迷信技能數(shù)量。我見過有人收集了幾百個技能結(jié)果代理加載慢、沖突多、效果差。十個精心維護(hù)的技能比一百個隨便寫的技能有用得多。技能的價(jià)值在于被使用不在于被收藏。最后分享一個我常用的小技巧給每個技能寫一句“失敗模式”放在SKILL.md末尾。比如“如果代理在測試失敗時(shí)直接改實(shí)現(xiàn)說明 TDD 技能未生效”。這樣排查問題時(shí)一眼就能定位。這個習(xí)慣幫我省了很多時(shí)間也讓我對技能的理解越來越深。