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