戰(zhàn)：用agent-skills與Claude Code實(shí)現(xiàn)TDD自動(dòng)化)
1. 從“agent-skills”說(shuō)起為什么它值得單獨(dú)拿出來(lái)聊第一次看到agent-skills這個(gè)標(biāo)題我腦子里蹦出來(lái)的不是某個(gè)具體工具而是一類(lèi)正在快速成型的東西——給 AI coding agent 用的“技能包”。你可以把它理解成一套可插拔的能力模塊agent 本身負(fù)責(zé)推理、規(guī)劃、調(diào)用工具而 skills 負(fù)責(zé)告訴它“遇到這類(lèi)任務(wù)時(shí)具體該怎么做、按什么順序做、做到什么程度算合格”。這個(gè)思路解決了一個(gè)很現(xiàn)實(shí)的問(wèn)題?，F(xiàn)在用 Claude Code、Cursor、Windsurf 這類(lèi) AI coding agent 的人越來(lái)越多但大家普遍會(huì)遇到同一個(gè)尷尬agent 很聰明可它不知道你團(tuán)隊(duì)的規(guī)范。比如你要求所有新功能必須先寫(xiě)測(cè)試再寫(xiě)實(shí)現(xiàn)它可能上來(lái)就給你把業(yè)務(wù)代碼寫(xiě)完了你要求提交前必須跑 lint 和類(lèi)型檢查它可能改完文件就直接說(shuō)“完成了”。每次都要在 prompt 里重復(fù)交代效率極低還容易漏。agent-skills這類(lèi)項(xiàng)目的核心價(jià)值就在這兒把重復(fù)的、有固定套路的工程實(shí)踐沉淀成 agent 可以直接加載和執(zhí)行的技能定義。它不是一個(gè)孤立的工具而是一種組織方式。配合skills CLI、Claude Code這類(lèi)運(yùn)行環(huán)境你可以把 TDD 流程、代碼審查清單、重構(gòu)規(guī)范、文檔生成模板全部打包成 skill讓 agent 在合適的時(shí)機(jī)自動(dòng)調(diào)用。這篇文章適合三類(lèi)人看一是已經(jīng)在用 Claude Code 或類(lèi)似 agent 工具、想進(jìn)一步提升自動(dòng)化程度的開(kāi)發(fā)者二是團(tuán)隊(duì)里負(fù)責(zé)制定工程規(guī)范、想讓 AI 真正落地到生產(chǎn)流程的技術(shù)負(fù)責(zé)人三是對(duì) AI coding agent 生態(tài)感興趣、想搞清楚“skills 到底是怎么回事”的同行。我會(huì)從設(shè)計(jì)思路、核心機(jī)制、實(shí)操落地、常見(jiàn)坑幾個(gè)角度把這件事講透。2. agent-skills 的整體設(shè)計(jì)與核心思路拆解2.1 為什么是“技能”而不是“提示詞”很多人第一反應(yīng)是這不就是高級(jí)一點(diǎn)的 prompt 嗎我直接把規(guī)范寫(xiě)進(jìn) system prompt 不就行了。剛開(kāi)始我也這么想但實(shí)際用下來(lái)會(huì)發(fā)現(xiàn)兩者有本質(zhì)區(qū)別。Prompt 是一次性、上下文相關(guān)的。你在一個(gè)會(huì)話(huà)里寫(xiě)了“先寫(xiě)測(cè)試”換個(gè)會(huì)話(huà)就沒(méi)了而且隨著對(duì)話(huà)變長(zhǎng)早期 prompt 的權(quán)重會(huì)被稀釋。Skill 是持久化、可復(fù)用、可組合的。它是一份獨(dú)立的定義文件有明確的觸發(fā)條件、執(zhí)行步驟和驗(yàn)收標(biāo)準(zhǔn)。agent 可以在需要的時(shí)候主動(dòng)加載它不需要你每次重復(fù)。更關(guān)鍵的是skill 把“知識(shí)”和“執(zhí)行”分開(kāi)了。知識(shí)部分是你團(tuán)隊(duì)積累的最佳實(shí)踐執(zhí)行部分是 agent 的推理和工具調(diào)用能力。這種分離帶來(lái)的好處是規(guī)范可以獨(dú)立迭代不用動(dòng) agent 本身同一個(gè) skill 可以被不同 agent、不同項(xiàng)目復(fù)用skill 之間還能互相引用形成能力網(wǎng)絡(luò)。從工程角度看這其實(shí)是在給 agent 建立一套可測(cè)試、可版本控制的行為契約。你可以像 review 代碼一樣 review skill 的定義可以給 skill 寫(xiě)測(cè)試用例可以在 CI 里驗(yàn)證 agent 是否真的按 skill 執(zhí)行了。這一點(diǎn)對(duì)于想把 AI 引入生產(chǎn)流程的團(tuán)隊(duì)來(lái)說(shuō)是決定性的。2.2 目錄結(jié)構(gòu)與加載機(jī)制的設(shè)計(jì)考量一個(gè)典型的agent-skills項(xiàng)目目錄結(jié)構(gòu)通常長(zhǎng)這樣agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ ├── examples/ │ │ └── scripts/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── checklist.md │ └── refactoring/ │ ├── SKILL.md │ └── patterns/ ├── cli/ │ └── index.ts └── package.json每個(gè) skill 一個(gè)目錄核心是SKILL.md。這個(gè)文件不是隨便寫(xiě)的文檔它有約定俗成的結(jié)構(gòu)元信息名稱(chēng)、描述、觸發(fā)條件 執(zhí)行步驟 示例 驗(yàn)收標(biāo)準(zhǔn)。agent 讀取這個(gè)文件后就能理解“什么時(shí)候該用這個(gè)技能”以及“用了之后要產(chǎn)出什么”。為什么用 Markdown 而不是 JSON 或 YAML因?yàn)?agent 本身就是靠自然語(yǔ)言推理的Markdown 對(duì)模型最友好可讀性也最好。你寫(xiě) JSON 描述步驟模型還得先解析結(jié)構(gòu)再理解語(yǔ)義多一層損耗。Markdown 直接就是模型訓(xùn)練時(shí)見(jiàn)過(guò)無(wú)數(shù)次的格式理解成本最低。加載機(jī)制上skills CLI通常提供幾個(gè)命令list列出所有可用技能show name查看某個(gè)技能的詳情install name把技能注冊(cè)到當(dāng)前 agent 環(huán)境。安裝的本質(zhì)是把 skill 目錄鏈接或復(fù)制到 agent 的配置路徑下讓 agent 在啟動(dòng)時(shí)能掃描到。這里有個(gè)設(shè)計(jì)細(xì)節(jié)值得注意技能是按需加載還是全量加載。全量加載簡(jiǎn)單但會(huì)占用上下文窗口按需加載需要 agent 有判斷能力實(shí)現(xiàn)復(fù)雜但更高效。目前主流做法是啟動(dòng)時(shí)只加載技能的元信息名稱(chēng)和描述真正執(zhí)行時(shí)才讀取完整內(nèi)容。2.3 與 Claude Code 等 agent 的協(xié)作方式agent-skills不是要替代 Claude Code而是增強(qiáng)它。Claude Code 本身有很強(qiáng)的代碼理解和工具調(diào)用能力但它默認(rèn)不知道你的工程規(guī)范。Skill 就是補(bǔ)上這一環(huán)。協(xié)作流程大致是這樣你在 Claude Code 里提出一個(gè)任務(wù)比如“給用戶(hù)模塊加一個(gè)手機(jī)號(hào)驗(yàn)證功能”。Claude Code 分析任務(wù)后發(fā)現(xiàn)這屬于“新功能開(kāi)發(fā)”于是查找已安裝的 skills找到test-driven-development加載它的定義。定義里寫(xiě)著第一步先寫(xiě)一個(gè)會(huì)失敗的測(cè)試第二步運(yùn)行測(cè)試確認(rèn)失敗第三步寫(xiě)最小實(shí)現(xiàn)讓測(cè)試通過(guò)第四步重構(gòu)。Claude Code 就按這個(gè)流程執(zhí)行每一步都調(diào)用相應(yīng)的工具寫(xiě)文件、跑命令、讀輸出。這個(gè)過(guò)程中skill 扮演的是流程控制器的角色。它不關(guān)心具體代碼怎么寫(xiě)那是 agent 的能力它關(guān)心的是“先做什么、后做什么、什么算做完”。這種分工讓 skill 可以跨語(yǔ)言、跨框架復(fù)用。同一個(gè) TDD skill用在 Python 項(xiàng)目和 TypeScript 項(xiàng)目上流程完全一樣只是 agent 生成的代碼不同。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 SKILL.md 到底該怎么寫(xiě)這是整個(gè)項(xiàng)目里最需要花心思的地方。寫(xiě)得好agent 執(zhí)行順暢寫(xiě)得爛agent 要么不觸發(fā)要么執(zhí)行到一半跑偏。我踩過(guò)幾次坑之后總結(jié)出一個(gè)比較穩(wěn)的模板--- name: test-driven-development description: 當(dāng)需要開(kāi)發(fā)新功能或修復(fù) bug 時(shí)使用確保先寫(xiě)測(cè)試再寫(xiě)實(shí)現(xiàn) trigger: 新功能開(kāi)發(fā)、bug 修復(fù)、代碼修改 --- ## 執(zhí)行步驟 1. 理解需求明確輸入輸出 2. 編寫(xiě)一個(gè)會(huì)失敗的測(cè)試用例 3. 運(yùn)行測(cè)試確認(rèn)它確實(shí)失敗 4. 編寫(xiě)最小實(shí)現(xiàn)讓測(cè)試通過(guò) 5. 運(yùn)行全部測(cè)試確認(rèn)沒(méi)有破壞其他功能 6. 重構(gòu)代碼保持測(cè)試通過(guò) ## 驗(yàn)收標(biāo)準(zhǔn) - 每個(gè)新功能都有對(duì)應(yīng)的測(cè)試 - 測(cè)試在實(shí)現(xiàn)之前編寫(xiě) - 所有測(cè)試通過(guò) - 沒(méi)有跳過(guò)或注釋掉的測(cè)試 ## 示例 附上一個(gè)完整的 TDD 循環(huán)示例幾個(gè)關(guān)鍵點(diǎn)。第一description要寫(xiě)清楚什么時(shí)候用而不是這是什么。模型是根據(jù)場(chǎng)景匹配技能的你寫(xiě)“測(cè)試驅(qū)動(dòng)開(kāi)發(fā)技能”它可能不知道啥時(shí)候該調(diào)用你寫(xiě)“當(dāng)需要開(kāi)發(fā)新功能或修復(fù) bug 時(shí)使用”匹配就準(zhǔn)確多了。第二步驟要可執(zhí)行、可驗(yàn)證。不要寫(xiě)“編寫(xiě)高質(zhì)量代碼”這種沒(méi)法驗(yàn)證的話(huà)要寫(xiě)“運(yùn)行npm test并確認(rèn)輸出中沒(méi)有 failing”。agent 需要明確的信號(hào)來(lái)判斷自己是否做對(duì)了。第三驗(yàn)收標(biāo)準(zhǔn)要獨(dú)立于實(shí)現(xiàn)。不要寫(xiě)“使用了 Jest 框架”要寫(xiě)“所有測(cè)試通過(guò)”。這樣 skill 才能跨技術(shù)棧復(fù)用。注意SKILL.md 不要寫(xiě)太長(zhǎng)。我見(jiàn)過(guò)有人寫(xiě)了三千字結(jié)果 agent 加載后反而抓不住重點(diǎn)。核心步驟控制在 10 條以?xún)?nèi)細(xì)節(jié)放到 examples 目錄里需要時(shí)再讀。3.2 skills CLI 的安裝與基本操作skills CLI是管理技能的命令行工具通常通過(guò) npm 全局安裝npm install -g agent-skills/cli安裝后驗(yàn)證skills --version skills listlist會(huì)掃描當(dāng)前項(xiàng)目或全局配置下的所有 skill輸出名稱(chēng)和描述。如果什么都沒(méi)顯示說(shuō)明還沒(méi)安裝任何技能。安裝一個(gè)技能skills install test-driven-development這個(gè)命令做的事情是從注冊(cè)表或本地路徑找到 skill 目錄復(fù)制到~/.agent-skills/下并在 agent 的配置文件中注冊(cè)。不同 agent 的配置路徑不一樣Claude Code 通常讀~/.claude/skills/CLI 會(huì)自動(dòng)處理路徑映射。查看某個(gè)技能的詳情skills show test-driven-development這會(huì)打印 SKILL.md 的完整內(nèi)容方便你在安裝前確認(rèn)它是否符合預(yù)期。移除技能skills remove test-driven-development這里有個(gè)實(shí)操心得安裝前先 show 一下。有些社區(qū)貢獻(xiàn)的 skill 寫(xiě)得比較粗糙觸發(fā)條件太寬泛裝上去之后 agent 動(dòng)不動(dòng)就調(diào)用反而干擾正常流程。先看內(nèi)容再?zèng)Q定裝不裝能省很多事。3.3 觸發(fā)條件的設(shè)計(jì)讓 agent 在對(duì)的時(shí)候做對(duì)的事觸發(fā)條件是 skill 設(shè)計(jì)里最微妙的部分。寫(xiě)得太窄agent 該用的時(shí)候想不起來(lái)寫(xiě)得太寬不該用的時(shí)候亂用。我的經(jīng)驗(yàn)是觸發(fā)條件應(yīng)該描述任務(wù)特征而不是技術(shù)關(guān)鍵詞。比如差的寫(xiě)法trigger: 當(dāng)用戶(hù)提到 test、jest、pytest 時(shí)好的寫(xiě)法trigger: 當(dāng)需要新增功能、修改現(xiàn)有行為、或修復(fù)缺陷時(shí)前者依賴(lài)關(guān)鍵詞匹配用戶(hù)換個(gè)說(shuō)法就失效了后者描述的是任務(wù)本質(zhì)不管用什么詞表達(dá)只要任務(wù)性質(zhì)對(duì)上了就能觸發(fā)。另外觸發(fā)條件之間要有互斥性。如果你裝了test-driven-development和quick-prototyping兩個(gè)技能前者要求先寫(xiě)測(cè)試后者要求先跑通再說(shuō)它們的觸發(fā)條件如果都覆蓋“新功能開(kāi)發(fā)”agent 就會(huì)糾結(jié)用哪個(gè)。解決辦法是在描述里加限定比如 TDD 用于“生產(chǎn)代碼”quick-prototyping 用于“探索性原型”。3.4 技能之間的組合與依賴(lài)單個(gè)技能能解決的問(wèn)題有限真正強(qiáng)大的是技能組合。比如一個(gè)完整的“功能開(kāi)發(fā)”流程可能涉及requirement-analysis把模糊需求拆成明確任務(wù)test-driven-development按 TDD 流程實(shí)現(xiàn)code-review自查代碼質(zhì)量documentation更新相關(guān)文檔這些技能可以串成一條流水線(xiàn)。實(shí)現(xiàn)方式有兩種一種是在 skill 里顯式引用其他 skill比如在feature-development的步驟里寫(xiě)“調(diào)用 test-driven-development 技能”另一種是讓 agent 自己根據(jù)當(dāng)前階段判斷該加載哪個(gè)。顯式引用的好處是流程可控壞處是靈活性差。隱式判斷的好處是靈活壞處是可能漏掉步驟。我的建議是核心流程用顯式引用輔助技能用隱式判斷。TDD 這種必須嚴(yán)格執(zhí)行的就寫(xiě)死在流程里文檔更新這種可以視情況而定的就讓 agent 自己決定。4. 實(shí)操過(guò)程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 從零搭建一個(gè) agent-skills 項(xiàng)目假設(shè)你要在團(tuán)隊(duì)里落地這套東西第一步是建倉(cāng)庫(kù)。我建議直接用 monorepo 結(jié)構(gòu)skills 和 CLI 放一起方便版本同步。mkdir agent-skills cd agent-skills npm init -y mkdir -p skills cli然后創(chuàng)建第一個(gè)技能mkdir -p skills/test-driven-development/examples touch skills/test-driven-development/SKILL.md把前面模板里的內(nèi)容填進(jìn)去。接著寫(xiě)一個(gè)最簡(jiǎn)單的 CLI核心功能就是掃描skills/目錄、解析 SKILL.md 的 frontmatter、提供 list 和 show 命令。// cli/index.js const fs require(fs); const path require(path); const SKILLS_DIR path.join(__dirname, .., skills); function listSkills() { const dirs fs.readdirSync(SKILLS_DIR); return dirs.map(dir { const skillPath path.join(SKILLS_DIR, dir, SKILL.md); if (!fs.existsSync(skillPath)) return null; const content fs.readFileSync(skillPath, utf-8); const match content.match(/name:\s*(.)/); const descMatch content.match(/description:\s*(.)/); return { name: match ? match[1].trim() : dir, description: descMatch ? descMatch[1].trim() : }; }).filter(Boolean); } const command process.argv[2]; if (command list) { console.table(listSkills()); }這個(gè)最小實(shí)現(xiàn)跑通后再逐步加 install、remove、sync 等命令。不要一上來(lái)就追求功能完整先把核心鏈路走通。4.2 在 Claude Code 中加載并驗(yàn)證技能Claude Code 的技能加載路徑通常是~/.claude/skills/。你可以手動(dòng)把 skill 目錄復(fù)制過(guò)去也可以用 CLI 的 install 命令。cp -r skills/test-driven-development ~/.claude/skills/然后在 Claude Code 里發(fā)起一個(gè)任務(wù)比如“給 utils 模塊加一個(gè)日期格式化函數(shù)”。觀察它的行為如果它先創(chuàng)建了測(cè)試文件運(yùn)行測(cè)試看到失敗再寫(xiě)實(shí)現(xiàn)說(shuō)明 skill 生效了。如果它直接寫(xiě)實(shí)現(xiàn)說(shuō)明觸發(fā)條件沒(méi)匹配上需要調(diào)整 SKILL.md 里的 description。驗(yàn)證的時(shí)候有個(gè)技巧故意給一個(gè)模糊的任務(wù)。比如“優(yōu)化一下用戶(hù)模塊”。好的 skill 應(yīng)該能讓 agent 先追問(wèn)清楚要優(yōu)化什么而不是直接動(dòng)手。如果 agent 上來(lái)就改代碼說(shuō)明 skill 里缺少“需求澄清”這一步。4.3 參數(shù)計(jì)算與選擇以測(cè)試覆蓋率為例Skill 里經(jīng)常需要設(shè)定量化標(biāo)準(zhǔn)比如測(cè)試覆蓋率。寫(xiě)多少合適我見(jiàn)過(guò)團(tuán)隊(duì)要求 100%結(jié)果 agent 為了湊覆蓋率寫(xiě)了一堆無(wú)意義的斷言反而降低了測(cè)試質(zhì)量。我的建議是分層次設(shè)定代碼類(lèi)型建議覆蓋率理由核心業(yè)務(wù)邏輯90% 以上出錯(cuò)代價(jià)高必須充分覆蓋工具函數(shù)80% 左右邏輯相對(duì)簡(jiǎn)單重點(diǎn)覆蓋邊界UI 組件60% 左右交互邏輯多快照測(cè)試為主配置文件不強(qiáng)制通常由集成測(cè)試覆蓋這個(gè)標(biāo)準(zhǔn)寫(xiě)進(jìn) skill 的驗(yàn)收條件里agent 就會(huì)按這個(gè)目標(biāo)執(zhí)行而不是盲目追求 100%。計(jì)算方式上用jest --coverage或pytest --cov輸出的行覆蓋率作為依據(jù)但要注意行覆蓋不等于邏輯覆蓋。一個(gè) if-else 只測(cè)了 if 分支行覆蓋率可能顯示 100%但 else 分支根本沒(méi)測(cè)。所以 skill 里最好加一條“關(guān)鍵分支必須有對(duì)應(yīng)用例”。4.4 實(shí)操現(xiàn)場(chǎng)一次完整的 TDD 技能執(zhí)行記錄我拿一個(gè)真實(shí)任務(wù)跑了一遍記錄如下。任務(wù)給一個(gè) Express 應(yīng)用加/health接口返回{ status: ok }。Agent 加載 TDD skill 后的執(zhí)行序列讀取SKILL.md確認(rèn)流程創(chuàng)建tests/health.test.js寫(xiě)入測(cè)試請(qǐng)求/health期望狀態(tài)碼 200body 為{ status: ok }運(yùn)行npm test輸出顯示Cannot GET /health測(cè)試失敗符合預(yù)期創(chuàng)建routes/health.js實(shí)現(xiàn)路由在app.js中注冊(cè)路由再次運(yùn)行npm test測(cè)試通過(guò)運(yùn)行npm run lint無(wú)報(bào)錯(cuò)輸出總結(jié)完成了什么、測(cè)試結(jié)果如何、下一步建議整個(gè)過(guò)程沒(méi)有人工干預(yù)耗時(shí)約 40 秒。對(duì)比不用 skill 的情況agent 通常會(huì)直接寫(xiě)路由和實(shí)現(xiàn)測(cè)試要么不寫(xiě)要么事后補(bǔ)一個(gè)走過(guò)場(chǎng)的。TDD skill 的價(jià)值就在于把順序鎖死了agent 沒(méi)有偷懶的空間。提示第一次跑的時(shí)候agent 可能會(huì)在“運(yùn)行測(cè)試確認(rèn)失敗”這一步卡住因?yàn)樗淮_定失敗是不是預(yù)期的。解決辦法是在 skill 里寫(xiě)清楚“確認(rèn)失敗信息與預(yù)期一致比如 404 而非語(yǔ)法錯(cuò)誤”。這樣 agent 就有了判斷依據(jù)。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 技能不觸發(fā)怎么辦這是最高頻的問(wèn)題。表現(xiàn)是明明裝了 skillagent 卻按自己的方式執(zhí)行。排查順序如下。先檢查 skill 是否真的被加載了。在 Claude Code 里輸入/skills或類(lèi)似命令看列表里有沒(méi)有。如果沒(méi)有檢查文件路徑對(duì)不對(duì)SKILL.md 的 frontmatter 格式是否正確。YAML frontmatter 對(duì)縮進(jìn)敏感name:前面不能有空格冒號(hào)后面要有一個(gè)空格。如果加載了但不觸發(fā)問(wèn)題多半在 description。把 description 改得更貼近任務(wù)描述。比如原來(lái)寫(xiě)“測(cè)試驅(qū)動(dòng)開(kāi)發(fā)”改成“當(dāng)需要編寫(xiě)新功能、修改現(xiàn)有邏輯或修復(fù)缺陷時(shí)按測(cè)試先行的方式執(zhí)行”。改完后重啟 agent 會(huì)話(huà)讓它重新讀取。還有一個(gè)隱蔽原因上下文里已經(jīng)有其他指令覆蓋了。比如你在 prompt 里寫(xiě)了“快速實(shí)現(xiàn)一個(gè) demo”agent 可能判斷這屬于原型開(kāi)發(fā)主動(dòng)跳過(guò)了 TDD skill。這時(shí)候要么調(diào)整 prompt要么給 skill 加一個(gè)更高優(yōu)先級(jí)的觸發(fā)條件。5.2 技能執(zhí)行到一半跑偏有時(shí)候 agent 開(kāi)始按 skill 執(zhí)行了但中途偏離。比如 TDD 流程走到“寫(xiě)最小實(shí)現(xiàn)”它卻順手把重構(gòu)也做了還改了不相關(guān)的文件。原因通常是 skill 的步驟描述不夠原子化。每一步應(yīng)該是一個(gè)獨(dú)立、可驗(yàn)證的動(dòng)作。不要寫(xiě)“實(shí)現(xiàn)功能并重構(gòu)”要拆成“實(shí)現(xiàn)功能運(yùn)行測(cè)試通過(guò)”和“重構(gòu)再次運(yùn)行測(cè)試通過(guò)”兩步。agent 在每一步結(jié)束時(shí)都有明確的完成信號(hào)就不容易越界。另外可以在 skill 里加一條約束“除非當(dāng)前步驟明確要求否則不要修改任務(wù)范圍之外的文件”。這句話(huà)能擋掉大部分跑偏行為。5.3 多個(gè)技能沖突的解決裝了多個(gè) skill 后agent 可能同時(shí)匹配到兩個(gè)。比如code-review和refactoring都可能在“代碼修改”后觸發(fā)。解決辦法是在 skill 里聲明優(yōu)先級(jí)和互斥關(guān)系?？梢栽?frontmatter 里加priority: 10 conflicts: [quick-prototyping]CLI 在加載時(shí)檢查沖突如果兩個(gè)互斥的 skill 同時(shí)匹配按優(yōu)先級(jí)高的執(zhí)行并提示用戶(hù)。這個(gè)機(jī)制需要 CLI 支持實(shí)現(xiàn)起來(lái)不復(fù)雜但能省很多調(diào)試時(shí)間。5.4 常見(jiàn)問(wèn)題速查表現(xiàn)象可能原因解決方法skill 不加載路徑錯(cuò)誤或 frontmatter 格式錯(cuò)檢查~/.claude/skills/下是否有對(duì)應(yīng)目錄驗(yàn)證 YAML 縮進(jìn)加載了不觸發(fā)description 太窄或太泛改成描述任務(wù)特征而非技術(shù)關(guān)鍵詞執(zhí)行中途跑偏步驟不夠原子化拆分步驟每步加驗(yàn)證條件多個(gè) skill 沖突觸發(fā)條件重疊加 priority 和 conflicts 聲明執(zhí)行結(jié)果不穩(wěn)定驗(yàn)收標(biāo)準(zhǔn)模糊把“高質(zhì)量”換成可量化的檢查項(xiàng)上下文占用過(guò)大skill 內(nèi)容太長(zhǎng)核心步驟精簡(jiǎn)細(xì)節(jié)移到 examples5.5 幾個(gè)我踩過(guò)的坑第一個(gè)坑在 skill 里寫(xiě)死了具體命令。比如寫(xiě)“運(yùn)行npm test”結(jié)果換到 Python 項(xiàng)目就失效了。后來(lái)改成“運(yùn)行項(xiàng)目對(duì)應(yīng)的測(cè)試命令”讓 agent 自己判斷通用性好了很多。第二個(gè)坑驗(yàn)收標(biāo)準(zhǔn)寫(xiě)得太主觀。寫(xiě)“代碼整潔”agent 覺(jué)得挺整潔我覺(jué)得不行。改成“函數(shù)不超過(guò) 50 行、沒(méi)有重復(fù)代碼塊、命名符合項(xiàng)目現(xiàn)有風(fēng)格”可操作性就強(qiáng)了。第三個(gè)坑忽略了 skill 的版本管理。團(tuán)隊(duì)里幾個(gè)人各自改 skill沒(méi)有版本控制導(dǎo)致行為不一致。后來(lái)把 skills 倉(cāng)庫(kù)納入 Git 管理每次修改走 PR問(wèn)題就解決了。6. 技能生態(tài)的擴(kuò)展與個(gè)人實(shí)踐體會(huì)agent-skills這套東西真正有意思的地方是它打開(kāi)了一個(gè)可積累的工程知識(shí)庫(kù)的可能性。你每解決一類(lèi)問(wèn)題就可以把解法沉淀成一個(gè) skill。時(shí)間長(zhǎng)了這個(gè)倉(cāng)庫(kù)就是你團(tuán)隊(duì)工程實(shí)踐的完整映射。新人入職裝上這套 skillsagent 就能按團(tuán)隊(duì)規(guī)范干活比看文檔快得多。我現(xiàn)在維護(hù)的 skills 倉(cāng)庫(kù)里除了 TDD還有幾個(gè)用得比較順的api-design負(fù)責(zé)按 RESTful 規(guī)范生成接口error-handling統(tǒng)一異常處理模式commit-message按約定式提交格式生成提交信息。每個(gè)都不復(fù)雜但組合起來(lái)agent 的產(chǎn)出質(zhì)量明顯上了一個(gè)臺(tái)階。擴(kuò)展方向上我覺(jué)得有兩個(gè)值得嘗試。一是技能的市場(chǎng)化社區(qū)貢獻(xiàn)、評(píng)分、按需安裝類(lèi)似 npm 的生態(tài)。二是技能的自動(dòng)化測(cè)試給每個(gè) skill 寫(xiě)測(cè)試用例在 CI 里跑確保 agent 按預(yù)期執(zhí)行。后者對(duì)生產(chǎn)環(huán)境尤其重要畢竟你不能指望每次都人工檢查 agent 有沒(méi)有偷懶。最后分享一個(gè)小技巧寫(xiě) skill 的時(shí)候先手動(dòng)跑一遍流程把每一步的實(shí)際操作和輸出記下來(lái)再整理成 skill 定義。這樣寫(xiě)出來(lái)的步驟最貼近真實(shí)執(zhí)行agent 理解起來(lái)也最順。憑空想象的流程往往會(huì)在某個(gè)環(huán)節(jié)卡住因?yàn)槟阕约憾紱](méi)實(shí)際走過(guò)。 AI編程Agent技能包實(shí)戰(zhàn)：用agent-skills與Claude Code實(shí)現(xiàn)TDD自動(dòng)化
1. 從“agent-skills”說(shuō)起為什么它值得單獨(dú)拿出來(lái)聊第一次看到agent-skills這個(gè)標(biāo)題我腦子里蹦出來(lái)的不是某個(gè)具體工具而是一類(lèi)正在快速成型的東西——給 AI coding agent 用的“技能包”。你可以把它理解成一套可插拔的能力模塊agent 本身負(fù)責(zé)推理、規(guī)劃、調(diào)用工具而 skills 負(fù)責(zé)告訴它“遇到這類(lèi)任務(wù)時(shí)具體該怎么做、按什么順序做、做到什么程度算合格”。這個(gè)思路解決了一個(gè)很現(xiàn)實(shí)的問(wèn)題?，F(xiàn)在用 Claude Code、Cursor、Windsurf 這類(lèi) AI coding agent 的人越來(lái)越多但大家普遍會(huì)遇到同一個(gè)尷尬agent 很聰明可它不知道你團(tuán)隊(duì)的規(guī)范。比如你要求所有新功能必須先寫(xiě)測(cè)試再寫(xiě)實(shí)現(xiàn)它可能上來(lái)就給你把業(yè)務(wù)代碼寫(xiě)完了你要求提交前必須跑 lint 和類(lèi)型檢查它可能改完文件就直接說(shuō)“完成了”。每次都要在 prompt 里重復(fù)交代效率極低還容易漏。agent-skills這類(lèi)項(xiàng)目的核心價(jià)值就在這兒把重復(fù)的、有固定套路的工程實(shí)踐沉淀成 agent 可以直接加載和執(zhí)行的技能定義。它不是一個(gè)孤立的工具而是一種組織方式。配合skills CLI、Claude Code這類(lèi)運(yùn)行環(huán)境你可以把 TDD 流程、代碼審查清單、重構(gòu)規(guī)范、文檔生成模板全部打包成 skill讓 agent 在合適的時(shí)機(jī)自動(dòng)調(diào)用。這篇文章適合三類(lèi)人看一是已經(jīng)在用 Claude Code 或類(lèi)似 agent 工具、想進(jìn)一步提升自動(dòng)化程度的開(kāi)發(fā)者二是團(tuán)隊(duì)里負(fù)責(zé)制定工程規(guī)范、想讓 AI 真正落地到生產(chǎn)流程的技術(shù)負(fù)責(zé)人三是對(duì) AI coding agent 生態(tài)感興趣、想搞清楚“skills 到底是怎么回事”的同行。我會(huì)從設(shè)計(jì)思路、核心機(jī)制、實(shí)操落地、常見(jiàn)坑幾個(gè)角度把這件事講透。2. agent-skills 的整體設(shè)計(jì)與核心思路拆解2.1 為什么是“技能”而不是“提示詞”很多人第一反應(yīng)是這不就是高級(jí)一點(diǎn)的 prompt 嗎我直接把規(guī)范寫(xiě)進(jìn) system prompt 不就行了。剛開(kāi)始我也這么想但實(shí)際用下來(lái)會(huì)發(fā)現(xiàn)兩者有本質(zhì)區(qū)別。Prompt 是一次性、上下文相關(guān)的。你在一個(gè)會(huì)話(huà)里寫(xiě)了“先寫(xiě)測(cè)試”換個(gè)會(huì)話(huà)就沒(méi)了而且隨著對(duì)話(huà)變長(zhǎng)早期 prompt 的權(quán)重會(huì)被稀釋。Skill 是持久化、可復(fù)用、可組合的。它是一份獨(dú)立的定義文件有明確的觸發(fā)條件、執(zhí)行步驟和驗(yàn)收標(biāo)準(zhǔn)。agent 可以在需要的時(shí)候主動(dòng)加載它不需要你每次重復(fù)。更關(guān)鍵的是skill 把“知識(shí)”和“執(zhí)行”分開(kāi)了。知識(shí)部分是你團(tuán)隊(duì)積累的最佳實(shí)踐執(zhí)行部分是 agent 的推理和工具調(diào)用能力。這種分離帶來(lái)的好處是規(guī)范可以獨(dú)立迭代不用動(dòng) agent 本身同一個(gè) skill 可以被不同 agent、不同項(xiàng)目復(fù)用skill 之間還能互相引用形成能力網(wǎng)絡(luò)。從工程角度看這其實(shí)是在給 agent 建立一套可測(cè)試、可版本控制的行為契約。你可以像 review 代碼一樣 review skill 的定義可以給 skill 寫(xiě)測(cè)試用例可以在 CI 里驗(yàn)證 agent 是否真的按 skill 執(zhí)行了。這一點(diǎn)對(duì)于想把 AI 引入生產(chǎn)流程的團(tuán)隊(duì)來(lái)說(shuō)是決定性的。2.2 目錄結(jié)構(gòu)與加載機(jī)制的設(shè)計(jì)考量一個(gè)典型的agent-skills項(xiàng)目目錄結(jié)構(gòu)通常長(zhǎng)這樣agent-skills/ ├── skills/ │ ├── test-driven-development/ │ │ ├── SKILL.md │ │ ├── examples/ │ │ └── scripts/ │ ├── code-review/ │ │ ├── SKILL.md │ │ └── checklist.md │ └── refactoring/ │ ├── SKILL.md │ └── patterns/ ├── cli/ │ └── index.ts └── package.json每個(gè) skill 一個(gè)目錄核心是SKILL.md。這個(gè)文件不是隨便寫(xiě)的文檔它有約定俗成的結(jié)構(gòu)元信息名稱(chēng)、描述、觸發(fā)條件 執(zhí)行步驟 示例 驗(yàn)收標(biāo)準(zhǔn)。agent 讀取這個(gè)文件后就能理解“什么時(shí)候該用這個(gè)技能”以及“用了之后要產(chǎn)出什么”。為什么用 Markdown 而不是 JSON 或 YAML因?yàn)?agent 本身就是靠自然語(yǔ)言推理的Markdown 對(duì)模型最友好可讀性也最好。你寫(xiě) JSON 描述步驟模型還得先解析結(jié)構(gòu)再理解語(yǔ)義多一層損耗。Markdown 直接就是模型訓(xùn)練時(shí)見(jiàn)過(guò)無(wú)數(shù)次的格式理解成本最低。加載機(jī)制上skills CLI通常提供幾個(gè)命令list列出所有可用技能show name查看某個(gè)技能的詳情install name把技能注冊(cè)到當(dāng)前 agent 環(huán)境。安裝的本質(zhì)是把 skill 目錄鏈接或復(fù)制到 agent 的配置路徑下讓 agent 在啟動(dòng)時(shí)能掃描到。這里有個(gè)設(shè)計(jì)細(xì)節(jié)值得注意技能是按需加載還是全量加載。全量加載簡(jiǎn)單但會(huì)占用上下文窗口按需加載需要 agent 有判斷能力實(shí)現(xiàn)復(fù)雜但更高效。目前主流做法是啟動(dòng)時(shí)只加載技能的元信息名稱(chēng)和描述真正執(zhí)行時(shí)才讀取完整內(nèi)容。2.3 與 Claude Code 等 agent 的協(xié)作方式agent-skills不是要替代 Claude Code而是增強(qiáng)它。Claude Code 本身有很強(qiáng)的代碼理解和工具調(diào)用能力但它默認(rèn)不知道你的工程規(guī)范。Skill 就是補(bǔ)上這一環(huán)。協(xié)作流程大致是這樣你在 Claude Code 里提出一個(gè)任務(wù)比如“給用戶(hù)模塊加一個(gè)手機(jī)號(hào)驗(yàn)證功能”。Claude Code 分析任務(wù)后發(fā)現(xiàn)這屬于“新功能開(kāi)發(fā)”于是查找已安裝的 skills找到test-driven-development加載它的定義。定義里寫(xiě)著第一步先寫(xiě)一個(gè)會(huì)失敗的測(cè)試第二步運(yùn)行測(cè)試確認(rèn)失敗第三步寫(xiě)最小實(shí)現(xiàn)讓測(cè)試通過(guò)第四步重構(gòu)。Claude Code 就按這個(gè)流程執(zhí)行每一步都調(diào)用相應(yīng)的工具寫(xiě)文件、跑命令、讀輸出。這個(gè)過(guò)程中skill 扮演的是流程控制器的角色。它不關(guān)心具體代碼怎么寫(xiě)那是 agent 的能力它關(guān)心的是“先做什么、后做什么、什么算做完”。這種分工讓 skill 可以跨語(yǔ)言、跨框架復(fù)用。同一個(gè) TDD skill用在 Python 項(xiàng)目和 TypeScript 項(xiàng)目上流程完全一樣只是 agent 生成的代碼不同。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 SKILL.md 到底該怎么寫(xiě)這是整個(gè)項(xiàng)目里最需要花心思的地方。寫(xiě)得好agent 執(zhí)行順暢寫(xiě)得爛agent 要么不觸發(fā)要么執(zhí)行到一半跑偏。我踩過(guò)幾次坑之后總結(jié)出一個(gè)比較穩(wěn)的模板--- name: test-driven-development description: 當(dāng)需要開(kāi)發(fā)新功能或修復(fù) bug 時(shí)使用確保先寫(xiě)測(cè)試再寫(xiě)實(shí)現(xiàn) trigger: 新功能開(kāi)發(fā)、bug 修復(fù)、代碼修改 --- ## 執(zhí)行步驟 1. 理解需求明確輸入輸出 2. 編寫(xiě)一個(gè)會(huì)失敗的測(cè)試用例 3. 運(yùn)行測(cè)試確認(rèn)它確實(shí)失敗 4. 編寫(xiě)最小實(shí)現(xiàn)讓測(cè)試通過(guò) 5. 運(yùn)行全部測(cè)試確認(rèn)沒(méi)有破壞其他功能 6. 重構(gòu)代碼保持測(cè)試通過(guò) ## 驗(yàn)收標(biāo)準(zhǔn) - 每個(gè)新功能都有對(duì)應(yīng)的測(cè)試 - 測(cè)試在實(shí)現(xiàn)之前編寫(xiě) - 所有測(cè)試通過(guò) - 沒(méi)有跳過(guò)或注釋掉的測(cè)試 ## 示例 附上一個(gè)完整的 TDD 循環(huán)示例幾個(gè)關(guān)鍵點(diǎn)。第一description要寫(xiě)清楚什么時(shí)候用而不是這是什么。模型是根據(jù)場(chǎng)景匹配技能的你寫(xiě)“測(cè)試驅(qū)動(dòng)開(kāi)發(fā)技能”它可能不知道啥時(shí)候該調(diào)用你寫(xiě)“當(dāng)需要開(kāi)發(fā)新功能或修復(fù) bug 時(shí)使用”匹配就準(zhǔn)確多了。第二步驟要可執(zhí)行、可驗(yàn)證。不要寫(xiě)“編寫(xiě)高質(zhì)量代碼”這種沒(méi)法驗(yàn)證的話(huà)要寫(xiě)“運(yùn)行npm test并確認(rèn)輸出中沒(méi)有 failing”。agent 需要明確的信號(hào)來(lái)判斷自己是否做對(duì)了。第三驗(yàn)收標(biāo)準(zhǔn)要獨(dú)立于實(shí)現(xiàn)。不要寫(xiě)“使用了 Jest 框架”要寫(xiě)“所有測(cè)試通過(guò)”。這樣 skill 才能跨技術(shù)棧復(fù)用。注意SKILL.md 不要寫(xiě)太長(zhǎng)。我見(jiàn)過(guò)有人寫(xiě)了三千字結(jié)果 agent 加載后反而抓不住重點(diǎn)。核心步驟控制在 10 條以?xún)?nèi)細(xì)節(jié)放到 examples 目錄里需要時(shí)再讀。3.2 skills CLI 的安裝與基本操作skills CLI是管理技能的命令行工具通常通過(guò) npm 全局安裝npm install -g agent-skills/cli安裝后驗(yàn)證skills --version skills listlist會(huì)掃描當(dāng)前項(xiàng)目或全局配置下的所有 skill輸出名稱(chēng)和描述。如果什么都沒(méi)顯示說(shuō)明還沒(méi)安裝任何技能。安裝一個(gè)技能skills install test-driven-development這個(gè)命令做的事情是從注冊(cè)表或本地路徑找到 skill 目錄復(fù)制到~/.agent-skills/下并在 agent 的配置文件中注冊(cè)。不同 agent 的配置路徑不一樣Claude Code 通常讀~/.claude/skills/CLI 會(huì)自動(dòng)處理路徑映射。查看某個(gè)技能的詳情skills show test-driven-development這會(huì)打印 SKILL.md 的完整內(nèi)容方便你在安裝前確認(rèn)它是否符合預(yù)期。移除技能skills remove test-driven-development這里有個(gè)實(shí)操心得安裝前先 show 一下。有些社區(qū)貢獻(xiàn)的 skill 寫(xiě)得比較粗糙觸發(fā)條件太寬泛裝上去之后 agent 動(dòng)不動(dòng)就調(diào)用反而干擾正常流程。先看內(nèi)容再?zèng)Q定裝不裝能省很多事。3.3 觸發(fā)條件的設(shè)計(jì)讓 agent 在對(duì)的時(shí)候做對(duì)的事觸發(fā)條件是 skill 設(shè)計(jì)里最微妙的部分。寫(xiě)得太窄agent 該用的時(shí)候想不起來(lái)寫(xiě)得太寬不該用的時(shí)候亂用。我的經(jīng)驗(yàn)是觸發(fā)條件應(yīng)該描述任務(wù)特征而不是技術(shù)關(guān)鍵詞。比如差的寫(xiě)法trigger: 當(dāng)用戶(hù)提到 test、jest、pytest 時(shí)好的寫(xiě)法trigger: 當(dāng)需要新增功能、修改現(xiàn)有行為、或修復(fù)缺陷時(shí)前者依賴(lài)關(guān)鍵詞匹配用戶(hù)換個(gè)說(shuō)法就失效了后者描述的是任務(wù)本質(zhì)不管用什么詞表達(dá)只要任務(wù)性質(zhì)對(duì)上了就能觸發(fā)。另外觸發(fā)條件之間要有互斥性。如果你裝了test-driven-development和quick-prototyping兩個(gè)技能前者要求先寫(xiě)測(cè)試后者要求先跑通再說(shuō)它們的觸發(fā)條件如果都覆蓋“新功能開(kāi)發(fā)”agent 就會(huì)糾結(jié)用哪個(gè)。解決辦法是在描述里加限定比如 TDD 用于“生產(chǎn)代碼”quick-prototyping 用于“探索性原型”。3.4 技能之間的組合與依賴(lài)單個(gè)技能能解決的問(wèn)題有限真正強(qiáng)大的是技能組合。比如一個(gè)完整的“功能開(kāi)發(fā)”流程可能涉及requirement-analysis把模糊需求拆成明確任務(wù)test-driven-development按 TDD 流程實(shí)現(xiàn)code-review自查代碼質(zhì)量documentation更新相關(guān)文檔這些技能可以串成一條流水線(xiàn)。實(shí)現(xiàn)方式有兩種一種是在 skill 里顯式引用其他 skill比如在feature-development的步驟里寫(xiě)“調(diào)用 test-driven-development 技能”另一種是讓 agent 自己根據(jù)當(dāng)前階段判斷該加載哪個(gè)。顯式引用的好處是流程可控壞處是靈活性差。隱式判斷的好處是靈活壞處是可能漏掉步驟。我的建議是核心流程用顯式引用輔助技能用隱式判斷。TDD 這種必須嚴(yán)格執(zhí)行的就寫(xiě)死在流程里文檔更新這種可以視情況而定的就讓 agent 自己決定。4. 實(shí)操過(guò)程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 從零搭建一個(gè) agent-skills 項(xiàng)目假設(shè)你要在團(tuán)隊(duì)里落地這套東西第一步是建倉(cāng)庫(kù)。我建議直接用 monorepo 結(jié)構(gòu)skills 和 CLI 放一起方便版本同步。mkdir agent-skills cd agent-skills npm init -y mkdir -p skills cli然后創(chuàng)建第一個(gè)技能mkdir -p skills/test-driven-development/examples touch skills/test-driven-development/SKILL.md把前面模板里的內(nèi)容填進(jìn)去。接著寫(xiě)一個(gè)最簡(jiǎn)單的 CLI核心功能就是掃描skills/目錄、解析 SKILL.md 的 frontmatter、提供 list 和 show 命令。// cli/index.js const fs require(fs); const path require(path); const SKILLS_DIR path.join(__dirname, .., skills); function listSkills() { const dirs fs.readdirSync(SKILLS_DIR); return dirs.map(dir { const skillPath path.join(SKILLS_DIR, dir, SKILL.md); if (!fs.existsSync(skillPath)) return null; const content fs.readFileSync(skillPath, utf-8); const match content.match(/name:\s*(.)/); const descMatch content.match(/description:\s*(.)/); return { name: match ? match[1].trim() : dir, description: descMatch ? descMatch[1].trim() : }; }).filter(Boolean); } const command process.argv[2]; if (command list) { console.table(listSkills()); }這個(gè)最小實(shí)現(xiàn)跑通后再逐步加 install、remove、sync 等命令。不要一上來(lái)就追求功能完整先把核心鏈路走通。4.2 在 Claude Code 中加載并驗(yàn)證技能Claude Code 的技能加載路徑通常是~/.claude/skills/。你可以手動(dòng)把 skill 目錄復(fù)制過(guò)去也可以用 CLI 的 install 命令。cp -r skills/test-driven-development ~/.claude/skills/然后在 Claude Code 里發(fā)起一個(gè)任務(wù)比如“給 utils 模塊加一個(gè)日期格式化函數(shù)”。觀察它的行為如果它先創(chuàng)建了測(cè)試文件運(yùn)行測(cè)試看到失敗再寫(xiě)實(shí)現(xiàn)說(shuō)明 skill 生效了。如果它直接寫(xiě)實(shí)現(xiàn)說(shuō)明觸發(fā)條件沒(méi)匹配上需要調(diào)整 SKILL.md 里的 description。驗(yàn)證的時(shí)候有個(gè)技巧故意給一個(gè)模糊的任務(wù)。比如“優(yōu)化一下用戶(hù)模塊”。好的 skill 應(yīng)該能讓 agent 先追問(wèn)清楚要優(yōu)化什么而不是直接動(dòng)手。如果 agent 上來(lái)就改代碼說(shuō)明 skill 里缺少“需求澄清”這一步。4.3 參數(shù)計(jì)算與選擇以測(cè)試覆蓋率為例Skill 里經(jīng)常需要設(shè)定量化標(biāo)準(zhǔn)比如測(cè)試覆蓋率。寫(xiě)多少合適我見(jiàn)過(guò)團(tuán)隊(duì)要求 100%結(jié)果 agent 為了湊覆蓋率寫(xiě)了一堆無(wú)意義的斷言反而降低了測(cè)試質(zhì)量。我的建議是分層次設(shè)定代碼類(lèi)型建議覆蓋率理由核心業(yè)務(wù)邏輯90% 以上出錯(cuò)代價(jià)高必須充分覆蓋工具函數(shù)80% 左右邏輯相對(duì)簡(jiǎn)單重點(diǎn)覆蓋邊界UI 組件60% 左右交互邏輯多快照測(cè)試為主配置文件不強(qiáng)制通常由集成測(cè)試覆蓋這個(gè)標(biāo)準(zhǔn)寫(xiě)進(jìn) skill 的驗(yàn)收條件里agent 就會(huì)按這個(gè)目標(biāo)執(zhí)行而不是盲目追求 100%。計(jì)算方式上用jest --coverage或pytest --cov輸出的行覆蓋率作為依據(jù)但要注意行覆蓋不等于邏輯覆蓋。一個(gè) if-else 只測(cè)了 if 分支行覆蓋率可能顯示 100%但 else 分支根本沒(méi)測(cè)。所以 skill 里最好加一條“關(guān)鍵分支必須有對(duì)應(yīng)用例”。4.4 實(shí)操現(xiàn)場(chǎng)一次完整的 TDD 技能執(zhí)行記錄我拿一個(gè)真實(shí)任務(wù)跑了一遍記錄如下。任務(wù)給一個(gè) Express 應(yīng)用加/health接口返回{ status: ok }。Agent 加載 TDD skill 后的執(zhí)行序列讀取SKILL.md確認(rèn)流程創(chuàng)建tests/health.test.js寫(xiě)入測(cè)試請(qǐng)求/health期望狀態(tài)碼 200body 為{ status: ok }運(yùn)行npm test輸出顯示Cannot GET /health測(cè)試失敗符合預(yù)期創(chuàng)建routes/health.js實(shí)現(xiàn)路由在app.js中注冊(cè)路由再次運(yùn)行npm test測(cè)試通過(guò)運(yùn)行npm run lint無(wú)報(bào)錯(cuò)輸出總結(jié)完成了什么、測(cè)試結(jié)果如何、下一步建議整個(gè)過(guò)程沒(méi)有人工干預(yù)耗時(shí)約 40 秒。對(duì)比不用 skill 的情況agent 通常會(huì)直接寫(xiě)路由和實(shí)現(xiàn)測(cè)試要么不寫(xiě)要么事后補(bǔ)一個(gè)走過(guò)場(chǎng)的。TDD skill 的價(jià)值就在于把順序鎖死了agent 沒(méi)有偷懶的空間。提示第一次跑的時(shí)候agent 可能會(huì)在“運(yùn)行測(cè)試確認(rèn)失敗”這一步卡住因?yàn)樗淮_定失敗是不是預(yù)期的。解決辦法是在 skill 里寫(xiě)清楚“確認(rèn)失敗信息與預(yù)期一致比如 404 而非語(yǔ)法錯(cuò)誤”。這樣 agent 就有了判斷依據(jù)。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 技能不觸發(fā)怎么辦這是最高頻的問(wèn)題。表現(xiàn)是明明裝了 skillagent 卻按自己的方式執(zhí)行。排查順序如下。先檢查 skill 是否真的被加載了。在 Claude Code 里輸入/skills或類(lèi)似命令看列表里有沒(méi)有。如果沒(méi)有檢查文件路徑對(duì)不對(duì)SKILL.md 的 frontmatter 格式是否正確。YAML frontmatter 對(duì)縮進(jìn)敏感name:前面不能有空格冒號(hào)后面要有一個(gè)空格。如果加載了但不觸發(fā)問(wèn)題多半在 description。把 description 改得更貼近任務(wù)描述。比如原來(lái)寫(xiě)“測(cè)試驅(qū)動(dòng)開(kāi)發(fā)”改成“當(dāng)需要編寫(xiě)新功能、修改現(xiàn)有邏輯或修復(fù)缺陷時(shí)按測(cè)試先行的方式執(zhí)行”。改完后重啟 agent 會(huì)話(huà)讓它重新讀取。還有一個(gè)隱蔽原因上下文里已經(jīng)有其他指令覆蓋了。比如你在 prompt 里寫(xiě)了“快速實(shí)現(xiàn)一個(gè) demo”agent 可能判斷這屬于原型開(kāi)發(fā)主動(dòng)跳過(guò)了 TDD skill。這時(shí)候要么調(diào)整 prompt要么給 skill 加一個(gè)更高優(yōu)先級(jí)的觸發(fā)條件。5.2 技能執(zhí)行到一半跑偏有時(shí)候 agent 開(kāi)始按 skill 執(zhí)行了但中途偏離。比如 TDD 流程走到“寫(xiě)最小實(shí)現(xiàn)”它卻順手把重構(gòu)也做了還改了不相關(guān)的文件。原因通常是 skill 的步驟描述不夠原子化。每一步應(yīng)該是一個(gè)獨(dú)立、可驗(yàn)證的動(dòng)作。不要寫(xiě)“實(shí)現(xiàn)功能并重構(gòu)”要拆成“實(shí)現(xiàn)功能運(yùn)行測(cè)試通過(guò)”和“重構(gòu)再次運(yùn)行測(cè)試通過(guò)”兩步。agent 在每一步結(jié)束時(shí)都有明確的完成信號(hào)就不容易越界。另外可以在 skill 里加一條約束“除非當(dāng)前步驟明確要求否則不要修改任務(wù)范圍之外的文件”。這句話(huà)能擋掉大部分跑偏行為。5.3 多個(gè)技能沖突的解決裝了多個(gè) skill 后agent 可能同時(shí)匹配到兩個(gè)。比如code-review和refactoring都可能在“代碼修改”后觸發(fā)。解決辦法是在 skill 里聲明優(yōu)先級(jí)和互斥關(guān)系?？梢栽?frontmatter 里加priority: 10 conflicts: [quick-prototyping]CLI 在加載時(shí)檢查沖突如果兩個(gè)互斥的 skill 同時(shí)匹配按優(yōu)先級(jí)高的執(zhí)行并提示用戶(hù)。這個(gè)機(jī)制需要 CLI 支持實(shí)現(xiàn)起來(lái)不復(fù)雜但能省很多調(diào)試時(shí)間。5.4 常見(jiàn)問(wèn)題速查表現(xiàn)象可能原因解決方法skill 不加載路徑錯(cuò)誤或 frontmatter 格式錯(cuò)檢查~/.claude/skills/下是否有對(duì)應(yīng)目錄驗(yàn)證 YAML 縮進(jìn)加載了不觸發(fā)description 太窄或太泛改成描述任務(wù)特征而非技術(shù)關(guān)鍵詞執(zhí)行中途跑偏步驟不夠原子化拆分步驟每步加驗(yàn)證條件多個(gè) skill 沖突觸發(fā)條件重疊加 priority 和 conflicts 聲明執(zhí)行結(jié)果不穩(wěn)定驗(yàn)收標(biāo)準(zhǔn)模糊把“高質(zhì)量”換成可量化的檢查項(xiàng)上下文占用過(guò)大skill 內(nèi)容太長(zhǎng)核心步驟精簡(jiǎn)細(xì)節(jié)移到 examples5.5 幾個(gè)我踩過(guò)的坑第一個(gè)坑在 skill 里寫(xiě)死了具體命令。比如寫(xiě)“運(yùn)行npm test”結(jié)果換到 Python 項(xiàng)目就失效了。后來(lái)改成“運(yùn)行項(xiàng)目對(duì)應(yīng)的測(cè)試命令”讓 agent 自己判斷通用性好了很多。第二個(gè)坑驗(yàn)收標(biāo)準(zhǔn)寫(xiě)得太主觀。寫(xiě)“代碼整潔”agent 覺(jué)得挺整潔我覺(jué)得不行。改成“函數(shù)不超過(guò) 50 行、沒(méi)有重復(fù)代碼塊、命名符合項(xiàng)目現(xiàn)有風(fēng)格”可操作性就強(qiáng)了。第三個(gè)坑忽略了 skill 的版本管理。團(tuán)隊(duì)里幾個(gè)人各自改 skill沒(méi)有版本控制導(dǎo)致行為不一致。后來(lái)把 skills 倉(cāng)庫(kù)納入 Git 管理每次修改走 PR問(wèn)題就解決了。6. 技能生態(tài)的擴(kuò)展與個(gè)人實(shí)踐體會(huì)agent-skills這套東西真正有意思的地方是它打開(kāi)了一個(gè)可積累的工程知識(shí)庫(kù)的可能性。你每解決一類(lèi)問(wèn)題就可以把解法沉淀成一個(gè) skill。時(shí)間長(zhǎng)了這個(gè)倉(cāng)庫(kù)就是你團(tuán)隊(duì)工程實(shí)踐的完整映射。新人入職裝上這套 skillsagent 就能按團(tuán)隊(duì)規(guī)范干活比看文檔快得多。我現(xiàn)在維護(hù)的 skills 倉(cāng)庫(kù)里除了 TDD還有幾個(gè)用得比較順的api-design負(fù)責(zé)按 RESTful 規(guī)范生成接口error-handling統(tǒng)一異常處理模式commit-message按約定式提交格式生成提交信息。每個(gè)都不復(fù)雜但組合起來(lái)agent 的產(chǎn)出質(zhì)量明顯上了一個(gè)臺(tái)階。擴(kuò)展方向上我覺(jué)得有兩個(gè)值得嘗試。一是技能的市場(chǎng)化社區(qū)貢獻(xiàn)、評(píng)分、按需安裝類(lèi)似 npm 的生態(tài)。二是技能的自動(dòng)化測(cè)試給每個(gè) skill 寫(xiě)測(cè)試用例在 CI 里跑確保 agent 按預(yù)期執(zhí)行。后者對(duì)生產(chǎn)環(huán)境尤其重要畢竟你不能指望每次都人工檢查 agent 有沒(méi)有偷懶。最后分享一個(gè)小技巧寫(xiě) skill 的時(shí)候先手動(dòng)跑一遍流程把每一步的實(shí)際操作和輸出記下來(lái)再整理成 skill 定義。這樣寫(xiě)出來(lái)的步驟最貼近真實(shí)執(zhí)行agent 理解起來(lái)也最順。憑空想象的流程往往會(huì)在某個(gè)環(huán)節(jié)卡住因?yàn)槟阕约憾紱](méi)實(shí)際走過(guò)。