1. 從 agent-skills 說起為什么我們需要給 AI 編程助手裝上技能包第一次看到agent-skills這個(gè)項(xiàng)目名的時(shí)候我腦子里蹦出來的第一個(gè)念頭是這不就是給 AI coding agents 做的一套外掛技能庫嗎后來翻了一圈資料、自己動(dòng)手跑了幾輪發(fā)現(xiàn)這個(gè)理解方向是對(duì)的但遠(yuǎn)不止這么簡(jiǎn)單。它本質(zhì)上是一套圍繞skills CLI構(gòu)建的、面向 AI 編程代理的能力擴(kuò)展體系核心目標(biāo)是讓 Claude Code 這類工具從能寫代碼進(jìn)化到知道該怎么寫、按什么流程寫、寫完怎么驗(yàn)證。說白了現(xiàn)在用 Claude Code 的人越來越多從安裝 Claude Code、在 VSCode 里配置 Claude Code到 Ubuntu 上折騰 Claude Code 環(huán)境入門門檻其實(shí)已經(jīng)降得很低了。但真正用起來你會(huì)發(fā)現(xiàn)一個(gè)尷尬的事實(shí)模型本身很聰明可它不知道你的項(xiàng)目規(guī)范、不知道你團(tuán)隊(duì)的測(cè)試流程、不知道你希望它先寫測(cè)試再寫實(shí)現(xiàn)。你每次都得在 prompt 里重復(fù)交代一遍累不累agent-skills要解決的就是這個(gè)問題——把那些重復(fù)的、有固定套路的工程實(shí)踐封裝成可復(fù)用、可組合的技能讓 AI agent 按需調(diào)用。這篇文章適合誰看如果你已經(jīng)在用 Claude Code或者正在研究 AI coding agents 的工程化落地尤其是對(duì)test-driven-development這類流程自動(dòng)化感興趣那接下來的內(nèi)容應(yīng)該能幫你少走不少彎路。我會(huì)從整體設(shè)計(jì)思路講到具體實(shí)操包括 skills CLI 的用法、技能怎么組織、TDD 流程怎么串起來以及我在實(shí)際配置中踩過的坑。2. agent-skills 的整體設(shè)計(jì)與核心思路拆解2.1 為什么是技能而不是提示詞模板很多人第一反應(yīng)是這不就是高級(jí)一點(diǎn)的 prompt template 嗎我一開始也這么想但用下來發(fā)現(xiàn)區(qū)別很大。提示詞模板是靜態(tài)的、扁平的你塞一段文字進(jìn)去模型讀完就完了。而agent-skills里的技能是有結(jié)構(gòu)的——它包含觸發(fā)條件、執(zhí)行步驟、依賴工具、驗(yàn)證標(biāo)準(zhǔn)這幾個(gè)維度。打個(gè)比方prompt template 像是給廚師一張菜譜紙條而 skill 像是給廚師一套完整的廚房 SOP什么情況下做這道菜、需要哪些食材、幾步完成、做完怎么檢查味道。這個(gè)差異在簡(jiǎn)單任務(wù)上看不出來但一旦涉及多步驟的工程流程比如 test-driven-development差距就非常明顯了。從工程角度看這種設(shè)計(jì)的好處是可組合性。一個(gè) skill 可以調(diào)用另一個(gè) skill就像函數(shù)調(diào)用一樣。你可以有一個(gè)寫測(cè)試的 skill一個(gè)跑測(cè)試的 skill一個(gè)根據(jù)失敗信息修復(fù)的 skill然后編排成一個(gè)完整的 TDD 循環(huán)。這種模塊化思路是agent-skills區(qū)別于普通提示詞管理的核心價(jià)值。2.2 skills CLI 的定位與選型考量skills CLI是這個(gè)體系里的命令行入口負(fù)責(zé)技能的安裝、管理、調(diào)用和版本控制。為什么要有 CLI因?yàn)?AI coding agents 的工作場(chǎng)景天然是終端驅(qū)動(dòng)的。你在 Claude Code 里讓它執(zhí)行終端命令它需要一個(gè)穩(wěn)定的、可腳本化的接口來操作技能庫。我試過幾種不同的組織方式純文件目錄、配置文件驅(qū)動(dòng)、以及 CLI 管理。實(shí)測(cè)下來 CLI 方案在幾個(gè)維度上勝出。第一是發(fā)現(xiàn)性skills list一敲當(dāng)前可用的技能一目了然第二是隔離性不同項(xiàng)目可以掛載不同的技能集不會(huì)互相污染第三是可升級(jí)性技能庫更新了直接skills update就行不用手動(dòng)同步文件。這里有個(gè)選型上的細(xì)節(jié)值得說為什么不用 npm 或者 pip 那種包管理思路因?yàn)榧寄艿牧６缺劝〉枚喽液芏嗉寄苁琼?xiàng)目私有的、不適合公開發(fā)布。CLI 方案更輕本地目錄加一個(gè)清單文件就能跑起來不需要注冊(cè)中心那一套重資產(chǎn)。2.3 與 Claude Code 的協(xié)作模式Claude Code 本身是一個(gè) agent 運(yùn)行時(shí)它負(fù)責(zé)理解你的意圖、規(guī)劃步驟、調(diào)用工具。agent-skills扮演的角色是知識(shí)供給方——當(dāng) Claude Code 判斷當(dāng)前任務(wù)需要某個(gè)技能時(shí)它通過 skills CLI 拉取對(duì)應(yīng)的技能定義然后按照技能里描述的步驟去執(zhí)行。這個(gè)協(xié)作模式有個(gè)關(guān)鍵點(diǎn)技能不是硬編碼進(jìn) agent 的而是運(yùn)行時(shí)動(dòng)態(tài)加載的。這意味著你可以隨時(shí)給 agent 增加新能力不用改 agent 本身的代碼。我在 Ubuntu 上配置 Claude Code 的時(shí)候特意驗(yàn)證過這一點(diǎn)把技能目錄指向一個(gè) Git 倉庫改完 push下次 agent 調(diào)用就是新版本非常順滑。注意技能加載是有優(yōu)先級(jí)的。項(xiàng)目級(jí)技能會(huì)覆蓋全局技能同名技能以項(xiàng)目級(jí)為準(zhǔn)。這個(gè)設(shè)計(jì)在團(tuán)隊(duì)協(xié)作里很實(shí)用但如果你不小心在項(xiàng)目里放了個(gè)半成品技能可能會(huì)覆蓋掉全局的好用版本排查起來容易懵。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 技能目錄結(jié)構(gòu)怎么組織才不亂一個(gè)技能的最小單元通常包含這幾個(gè)文件SKILL.md技能描述和步驟、config.json元數(shù)據(jù)和觸發(fā)條件、以及可選的scripts/目錄輔助腳本。我見過有人把所有技能平鋪在一個(gè)目錄里十幾個(gè)技能之后就開始找不著北了。推薦按領(lǐng)域分層skills/ testing/ tdd-cycle/ coverage-check/ refactor/ extract-function/ docs/ api-doc-gen/這樣組織的好處是skills list輸出的時(shí)候天然帶分組而且批量啟用/禁用某個(gè)領(lǐng)域很方便。我在實(shí)際項(xiàng)目里還會(huì)加一個(gè)_local/目錄放實(shí)驗(yàn)性技能跟穩(wěn)定技能隔離開避免誤觸發(fā)。3.2 觸發(fā)條件的設(shè)計(jì)讓 agent 知道什么時(shí)候該用這是整個(gè)體系里最容易被低估的部分。技能寫得再好如果 agent 不知道什么時(shí)候該調(diào)用它等于白搭。觸發(fā)條件一般寫在config.json里支持幾種匹配方式關(guān)鍵詞匹配、文件類型匹配、任務(wù)類型匹配。舉個(gè)例子一個(gè) TDD 技能的觸發(fā)條件可能是這樣的{ name: tdd-cycle, triggers: { keywords: [實(shí)現(xiàn), 新功能, feature, implement], filePatterns: [*.py, *.ts, *.go], taskTypes: [coding] }, priority: 10 }這里priority是個(gè)關(guān)鍵參數(shù)。當(dāng)多個(gè)技能同時(shí)匹配時(shí)優(yōu)先級(jí)高的先執(zhí)行。我一般把流程性技能比如 TDD設(shè)高優(yōu)先級(jí)工具性技能比如格式化設(shè)低優(yōu)先級(jí)這樣 agent 會(huì)先走流程再調(diào)工具。實(shí)操心得觸發(fā)關(guān)鍵詞不要設(shè)太寬泛。我一開始把寫設(shè)成觸發(fā)詞結(jié)果 agent 連寫個(gè)注釋都要走一遍完整 TDD 流程煩得不行。后來改成實(shí)現(xiàn)新增功能這類明確的開發(fā)意圖詞誤觸發(fā)率大幅下降。3.3 技能之間的依賴與編排單個(gè)技能能做的事有限真正的威力在于編排。agent-skills支持在技能里聲明依賴比如 TDD 技能依賴生成測(cè)試骨架和運(yùn)行測(cè)試兩個(gè)子技能。聲明方式是在SKILL.md的 frontmatter 里寫--- name: tdd-cycle depends_on: - test-scaffold - test-runner - failure-analyzer ---運(yùn)行時(shí)skills CLI 會(huì)先解析依賴樹確保所有依賴技能都已加載然后按拓?fù)漤樞驁?zhí)行。這個(gè)機(jī)制在復(fù)雜流程里特別有用但也帶來一個(gè)坑循環(huán)依賴會(huì)導(dǎo)致加載失敗。我踩過一次A 依賴 BB 又依賴 ACLI 直接報(bào)錯(cuò)退出排查了半天才發(fā)現(xiàn)是技能設(shè)計(jì)上的邏輯閉環(huán)問題。4. 實(shí)操過程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 環(huán)境準(zhǔn)備從零把 skills CLI 跑起來假設(shè)你已經(jīng)在 Ubuntu 或者 macOS 上裝好了 Claude Code接下來裝 skills CLI。我實(shí)測(cè)下來最穩(wěn)的方式是通過包管理器安裝避免手動(dòng)編譯帶來的依賴問題。# 以 npm 全局安裝為例 npm install -g agent-skills/cli # 驗(yàn)證安裝 skills --version裝完之后初始化一個(gè)技能工作區(qū)skills init my-skills cd my-skills這個(gè)命令會(huì)生成一個(gè)標(biāo)準(zhǔn)的目錄骨架包括skills/、config.yaml和一個(gè)示例技能。我建議先別急著刪示例跑一遍skills list確認(rèn) CLI 能正確識(shí)別再開始加自己的技能。如果你是在 VSCode 里配合 Claude Code 使用還需要在 VSCode 的設(shè)置里把 skills CLI 的路徑加到環(huán)境變量否則 Claude Code 調(diào)用終端命令時(shí)可能找不到skills這個(gè)可執(zhí)行文件。這個(gè)細(xì)節(jié)官方文檔里提得不多但實(shí)際配置中很容易卡住。4.2 寫第一個(gè)技能以 test-driven-development 為例TDD 是agent-skills最典型的應(yīng)用場(chǎng)景因?yàn)樗鞒坦潭?、步驟明確、驗(yàn)證標(biāo)準(zhǔn)清晰。一個(gè)完整的 TDD 技能應(yīng)該包含三個(gè)階段紅寫失敗測(cè)試、綠寫最小實(shí)現(xiàn)讓測(cè)試通過、重構(gòu)優(yōu)化代碼保持測(cè)試通過。先寫SKILL.md--- name: tdd-cycle description: 按測(cè)試驅(qū)動(dòng)開發(fā)流程實(shí)現(xiàn)新功能 depends_on: - test-scaffold - test-runner --- ## 執(zhí)行步驟 1. 分析需求識(shí)別需要測(cè)試的行為邊界 2. 調(diào)用 test-scaffold 生成測(cè)試文件骨架 3. 編寫至少一個(gè)會(huì)失敗的測(cè)試用例 4. 調(diào)用 test-runner 運(yùn)行測(cè)試確認(rèn)測(cè)試失敗紅 5. 編寫最小實(shí)現(xiàn)代碼讓測(cè)試通過綠 6. 運(yùn)行全部測(cè)試確認(rèn)無回歸 7. 在測(cè)試保護(hù)下重構(gòu)代碼 8. 重復(fù) 3-7 直到需求完成這里的關(guān)鍵設(shè)計(jì)是強(qiáng)制驗(yàn)證失敗。很多 AI agent 會(huì)跳過確認(rèn)測(cè)試失敗這一步直接寫實(shí)現(xiàn)結(jié)果測(cè)試到底有沒有真正覆蓋到邏輯根本不知道。技能里明確寫死這一步agent 就必須執(zhí)行。然后是test-scaffold技能負(fù)責(zé)根據(jù)語言和框架生成測(cè)試文件{ name: test-scaffold, language: auto-detect, frameworks: { python: pytest, javascript: jest, go: testing } }test-runner則封裝了運(yùn)行命令和結(jié)果解析邏輯把測(cè)試輸出轉(zhuǎn)成 agent 能理解的結(jié)構(gòu)化信息。4.3 參數(shù)計(jì)算與選擇測(cè)試覆蓋率閾值怎么定TDD 流程里有個(gè)繞不開的參數(shù)覆蓋率閾值。設(shè)太高agent 會(huì)為了湊覆蓋率寫一堆無意義的測(cè)試設(shè)太低又起不到保護(hù)作用。我的經(jīng)驗(yàn)是按項(xiàng)目階段分檔項(xiàng)目階段建議行覆蓋率建議分支覆蓋率說明原型驗(yàn)證40%30%快速迭代優(yōu)先別被測(cè)試拖死功能開發(fā)70%60%核心邏輯必須覆蓋生產(chǎn)維護(hù)85%75%回歸風(fēng)險(xiǎn)高測(cè)試要扎實(shí)核心庫95%90%對(duì)外接口容錯(cuò)空間極小這個(gè)閾值不是拍腦袋定的。行覆蓋率 70% 大致對(duì)應(yīng)每個(gè)函數(shù)至少被調(diào)用一次分支覆蓋率 60% 對(duì)應(yīng)主要條件分支都有覆蓋。再往上每提升 5%邊際成本會(huì)明顯上升因?yàn)橐采w的都是異常路徑和邊界條件寫起來費(fèi)勁。在技能配置里這個(gè)閾值作為參數(shù)傳給test-runnertest-runner: coverage: line: 70 branch: 60 failOnThreshold: truefailOnThreshold: true意味著覆蓋率不達(dá)標(biāo)時(shí)測(cè)試直接判失敗agent 必須補(bǔ)測(cè)試。這個(gè)開關(guān)我建議在功能開發(fā)階段打開原型階段關(guān)掉。4.4 實(shí)操現(xiàn)場(chǎng)一次完整的 TDD 循環(huán)記錄我拿一個(gè)真實(shí)的小需求跑了一遍給一個(gè) Python 工具函數(shù)加輸入校驗(yàn)。下面是實(shí)際的過程記錄。第一步agent 識(shí)別到新增功能關(guān)鍵詞觸發(fā)tdd-cycle技能。它先調(diào)用test-scaffold在tests/test_validator.py里生成了骨架import pytest from validator import validate_input def test_validate_input_rejects_empty(): # TODO: 實(shí)現(xiàn)測(cè)試 pass第二步agent 填充測(cè)試用例def test_validate_input_rejects_empty(): with pytest.raises(ValueError): validate_input() def test_validate_input_accepts_normal_string(): assert validate_input(hello) hello第三步調(diào)用test-runner跑測(cè)試。因?yàn)関alidate_input還不存在測(cè)試報(bào) ImportError符合紅的預(yù)期。agent 記錄下失敗信息。第四步寫最小實(shí)現(xiàn)def validate_input(value): if not value: raise ValueError(input cannot be empty) return value第五步再跑測(cè)試兩個(gè)用例都通過進(jìn)入綠狀態(tài)。第六步agent 檢查是否有重構(gòu)空間發(fā)現(xiàn)邏輯已經(jīng)足夠簡(jiǎn)潔結(jié)束循環(huán)。整個(gè)過程大概花了 40 秒比我手動(dòng)寫快不少而且測(cè)試是先寫的覆蓋有保證。這個(gè)流程跑順之后我基本把新功能的實(shí)現(xiàn)都交給它了。5. 常見問題與排查技巧實(shí)錄5.1 技能不觸發(fā)怎么辦這是最高頻的問題。agent 該用技能的時(shí)候沒用八成是觸發(fā)條件沒匹配上。排查順序是這樣的先skills list --verbose看技能是否加載成功再用skills match 你的任務(wù)描述手動(dòng)測(cè)試匹配結(jié)果如果匹配為空檢查關(guān)鍵詞是否覆蓋了你的表達(dá)方式。我遇到過一個(gè)典型案例技能里配的關(guān)鍵詞是重構(gòu)但我習(xí)慣說優(yōu)化這段代碼結(jié)果死活不觸發(fā)。后來在關(guān)鍵詞列表里補(bǔ)了優(yōu)化整理清理問題解決。所以關(guān)鍵詞要覆蓋同義詞別只寫一個(gè)。5.2 技能執(zhí)行到一半卡住這種情況通常是依賴技能缺失或者外部命令超時(shí)。先看skills doctor的輸出它會(huì)檢查所有技能的依賴完整性和命令可用性。如果是超時(shí)調(diào)整config.json里的timeout參數(shù)默認(rèn)是 30 秒跑大型測(cè)試套件可能不夠我一般設(shè)成 120 秒。還有一種卡住是 agent 在等用戶確認(rèn)。有些技能步驟設(shè)計(jì)成了需要人工介入如果你希望全自動(dòng)得在技能里把requireConfirmation設(shè)成false。但我要提醒一句涉及刪除文件、修改數(shù)據(jù)庫這類危險(xiǎn)操作還是保留確認(rèn)步驟比較穩(wěn)妥。5.3 常見問題速查表問題現(xiàn)象可能原因排查方法解決方案技能不觸發(fā)關(guān)鍵詞不匹配skills match 描述補(bǔ)充同義詞到 triggers加載失敗循環(huán)依賴skills doctor打破依賴環(huán)抽公共技能執(zhí)行超時(shí)timeout 太短查看日志時(shí)間戳調(diào)大 timeout 參數(shù)覆蓋率不達(dá)標(biāo)閾值過高查看覆蓋率報(bào)告分階段調(diào)整閾值技能版本混亂項(xiàng)目級(jí)覆蓋全局skills list --scope明確技能作用域命令找不到PATH 未配置which skills配置環(huán)境變量5.4 幾個(gè)我踩過的坑第一個(gè)坑是技能命名沖突。我在全局和項(xiàng)目里各放了一個(gè)叫format的技能結(jié)果項(xiàng)目級(jí)的那個(gè)功能不全把全局的好版本覆蓋了格式化出來的代碼風(fēng)格亂七八糟。后來養(yǎng)成習(xí)慣項(xiàng)目級(jí)技能一律加前綴比如proj-format避免撞名。第二個(gè)坑是過度自動(dòng)化。一開始我恨不得把所有操作都做成技能連讀文件都想封裝。結(jié)果技能庫膨脹到幾十個(gè)agent 每次匹配都要遍歷一遍響應(yīng)變慢而且很多技能根本用不上。后來砍到十幾個(gè)核心技能反而更高效。技能不是越多越好夠用就行。第三個(gè)坑是忽略技能的可測(cè)試性。技能本身也是代碼也需要測(cè)試。我現(xiàn)在的做法是給每個(gè)技能寫一個(gè)最小的驗(yàn)證用例放在tests/目錄下改完技能跑一遍確保沒改壞。這個(gè)習(xí)慣幫我避免了好幾次改一個(gè)技能崩三個(gè)流程的慘劇。6. 技能庫的維護(hù)與團(tuán)隊(duì)協(xié)作實(shí)踐6.1 版本管理技能也要走 Git技能庫本質(zhì)上是代碼資產(chǎn)必須納入版本控制。我的做法是每個(gè)技能一個(gè)目錄整個(gè)技能庫一個(gè) Git 倉庫用分支管理不同環(huán)境的技能集。main分支放穩(wěn)定技能dev分支放實(shí)驗(yàn)性技能通過 CI 自動(dòng)跑技能驗(yàn)證用例。這里有個(gè)細(xì)節(jié)技能的config.json里可以聲明minCliVersion指定最低兼容的 CLI 版本。這樣當(dāng)團(tuán)隊(duì)里有人 CLI 版本太老時(shí)加載技能會(huì)直接報(bào)錯(cuò)提示升級(jí)而不是莫名其妙地行為異常。這個(gè)字段在團(tuán)隊(duì)協(xié)作里特別有用能避免我這兒好好的你那兒怎么不行的扯皮。6.2 團(tuán)隊(duì)共享怎么讓技能庫不變成個(gè)人玩具一個(gè)人用技能庫和一群人用完全是兩碼事。團(tuán)隊(duì)共享最大的挑戰(zhàn)是約定統(tǒng)一。比如 TDD 技能里測(cè)試失敗確認(rèn)這一步有人覺得必要有人覺得浪費(fèi)時(shí)間。這種分歧必須在技能設(shè)計(jì)階段就解決否則技能庫會(huì)分裂成好幾套。我的經(jīng)驗(yàn)是搞一個(gè)技能評(píng)審會(huì)每個(gè)新技能上線前過一遍重點(diǎn)看三件事觸發(fā)條件是否明確、步驟是否可復(fù)現(xiàn)、驗(yàn)證標(biāo)準(zhǔn)是否客觀。評(píng)審?fù)ㄟ^的技能才能進(jìn)main分支。這個(gè)過程一開始有點(diǎn)重但跑順之后技能庫的質(zhì)量會(huì)明顯高于各自為戰(zhàn)的方案。6.3 與 Claude Code 的深度集成技巧Claude Code 支持通過配置文件掛載外部技能庫。在項(xiàng)目根目錄的.claude/config.json里加上{ skills: { path: ./skills, autoLoad: true, cliPath: /usr/local/bin/skills } }autoLoad: true意味著 Claude Code 啟動(dòng)時(shí)自動(dòng)加載技能庫不用每次手動(dòng)初始化。cliPath指定 CLI 的絕對(duì)路徑避免 PATH 問題。還有一個(gè)進(jìn)階技巧把技能庫和項(xiàng)目的 CI 打通。每次 push 代碼時(shí)CI 自動(dòng)跑一遍技能驗(yàn)證用例確保技能和代碼同步演進(jìn)。我在一個(gè)項(xiàng)目里這么做了之后技能失效的情況基本絕跡了。提示如果你在 VSCode 里用 Claude Code 插件記得在插件設(shè)置里也配一遍技能路徑。插件和 CLI 是兩套配置容易漏掉一個(gè)。7. 我對(duì) agent-skills 這套東西的真實(shí)看法用了一段時(shí)間之后我的整體判斷是agent-skills解決的是 AI coding agents 從能用到好用之間的那道坎。模型能力本身在快速進(jìn)步但工程流程的規(guī)范化、可復(fù)用化是模型自己搞不定的必須靠外部體系來補(bǔ)。技能庫就是這個(gè)補(bǔ)丁。它不適合所有人。如果你只是偶爾用 Claude Code 寫個(gè)小腳本配技能庫的投入產(chǎn)出比不高。但如果你在團(tuán)隊(duì)里推 AI 輔助開發(fā)或者有大量重復(fù)性的工程流程需要固化那這套東西的價(jià)值就體現(xiàn)出來了。尤其是 test-driven-development 這種流程一旦封裝成技能整個(gè)團(tuán)隊(duì)的開發(fā)節(jié)奏都會(huì)被帶起來。后續(xù)我打算探索的方向是把技能庫和代碼審查流程結(jié)合讓 agent 在提交前自動(dòng)跑一遍技能檢查把常見問題攔在 CI 之前。這個(gè)想法還在驗(yàn)證階段等跑通了再單獨(dú)寫一篇。如果你也在折騰類似的東西歡迎交流踩坑經(jīng)驗(yàn)這類工程化的細(xì)節(jié)一個(gè)人摸索太慢了。