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