1. 從 agent-skills 說(shuō)起為什么 AI 編碼代理需要一套技能體系第一次看到agent-skills這個(gè)項(xiàng)目名的時(shí)候我的直覺(jué)是這大概率又是一個(gè)把提示詞打包成模板的倉(cāng)庫(kù)。但真正翻完它的結(jié)構(gòu)、跑通它的 CLI、再把它接到 Claude Code 里用了幾輪之后我改主意了。它解決的不是提示詞怎么寫的問(wèn)題而是AI 編碼代理怎么穩(wěn)定地做對(duì)一件事的問(wèn)題——這兩件事的難度差了一個(gè)量級(jí)。先把概念說(shuō)清楚。所謂agent-skills本質(zhì)上是給 AI 編碼代理AI coding agents準(zhǔn)備的一套可復(fù)用、可組合、可被程序化調(diào)用的能力單元。每個(gè) skill 通常包含三部分一段描述這個(gè)能力做什么的元信息、一份指導(dǎo)代理如何執(zhí)行的操作說(shuō)明、以及可選的輔助腳本或資源文件。代理在接到任務(wù)時(shí)不是靠一段萬(wàn)能提示詞硬扛而是先判斷這個(gè)任務(wù)該調(diào)用哪個(gè) skill再按 skill 里定義的流程一步步執(zhí)行。這套思路為什么重要因?yàn)榇竽Ｐ驮诰幋a場(chǎng)景里最大的問(wèn)題從來(lái)不是不會(huì)寫代碼而是不穩(wěn)定。同一個(gè)需求今天給你寫個(gè)能跑的版本明天給你寫個(gè)漏了邊界條件的版本后天干脆把測(cè)試文件也一起改了。test-driven-development這類 skill 的價(jià)值就在于它把先寫測(cè)試、再寫實(shí)現(xiàn)、最后重構(gòu)這個(gè)流程固化下來(lái)讓代理每次都必須走同一條路而不是自由發(fā)揮。這個(gè)項(xiàng)目適合誰(shuí)三類人最該看一是已經(jīng)在用 Claude Code 或類似工具、但總覺(jué)得輸出質(zhì)量飄忽的開(kāi)發(fā)者二是想把 AI 編碼能力集成進(jìn)自己 CI/CD 或內(nèi)部工具鏈的工程團(tuán)隊(duì)三是想理解代理工程這套方法論到底怎么落地的人。哪怕你只是剛裝完 Claude Code 想找個(gè)靠譜的起點(diǎn)這套 skill 組織方式也比你自己攢一堆提示詞要省事得多。下面我會(huì)按設(shè)計(jì)思路—核心細(xì)節(jié)—實(shí)操落地—問(wèn)題排查這條線把 agent-skills 從里到外拆一遍中間會(huì)穿插我自己踩過(guò)的坑和實(shí)測(cè)有效的配置。2. 整體設(shè)計(jì)與思路拆解為什么是技能而不是提示詞2.1 從提示詞工程到技能工程的范式轉(zhuǎn)變?cè)鐑赡甏蠹彝?AI 編碼主流做法是攢一個(gè)超長(zhǎng)的 system prompt把編碼規(guī)范、項(xiàng)目結(jié)構(gòu)、命名習(xí)慣全塞進(jìn)去。這套做法在小項(xiàng)目上還能湊合一旦項(xiàng)目變大就崩了——提示詞越長(zhǎng)模型對(duì)其中每一條的注意力越稀釋最后變成什么都說(shuō)了等于什么都沒(méi)說(shuō)。agent-skills 的設(shè)計(jì)思路正好相反把一個(gè)大而全的提示詞拆成一堆小而專的技能。每個(gè) skill 只負(fù)責(zé)一件事比如寫單元測(cè)試做代碼審查生成數(shù)據(jù)庫(kù)遷移腳本。代理在執(zhí)行任務(wù)時(shí)按需加載上下文里只出現(xiàn)當(dāng)前真正需要的那部分指令。這個(gè)轉(zhuǎn)變帶來(lái)的直接好處是上下文利用率大幅提升間接好處是每個(gè) skill 都可以獨(dú)立迭代、獨(dú)立測(cè)試。我打個(gè)生活化的比方。傳統(tǒng)提示詞像是一本厚厚的員工手冊(cè)新員工入職先背完整本干活時(shí)還得自己翻。技能體系更像是貼在工位旁邊的一張張操作卡片做咖啡的時(shí)候看咖啡那張修打印機(jī)的時(shí)候看打印機(jī)那張。手冊(cè)不會(huì)消失但它退居到背景知識(shí)的位置真正指導(dǎo)動(dòng)作的是那些卡片。2.2 技能目錄結(jié)構(gòu)背后的考量一個(gè)典型的 skill 目錄長(zhǎng)這樣skills/ test-driven-development/ SKILL.md scripts/ run-tests.sh references/ testing-patterns.md code-review/ SKILL.md核心是那個(gè)SKILL.md它承擔(dān)了元信息和操作說(shuō)明兩個(gè)職責(zé)。文件開(kāi)頭通常有一段結(jié)構(gòu)化的元數(shù)據(jù)聲明這個(gè) skill 的名字、適用場(chǎng)景、觸發(fā)條件正文部分則是給代理看的操作指南。把腳本和參考資料放在子目錄里是為了讓 skill 保持自包含——一個(gè) skill 文件夾拷到哪都能用不依賴外部路徑。提示SKILL.md 里的描述要寫得像給一個(gè)新同事交代任務(wù)而不是像寫 API 文檔。代理理解自然語(yǔ)言指令的能力遠(yuǎn)強(qiáng)于理解結(jié)構(gòu)化配置把什么時(shí)候用、怎么用、注意什么用大白話講清楚效果比堆參數(shù)好得多。2.3 與 Claude Code 的契合點(diǎn)在哪里Claude Code 這類工具的一個(gè)關(guān)鍵特性是它能讀寫文件、執(zhí)行終端命令、并且能在多輪對(duì)話里保持任務(wù)上下文。agent-skills 恰好利用了這三點(diǎn)skill 文件本身是文件代理可以直接讀skill 里的腳本可以通過(guò)終端執(zhí)行整個(gè)讀 skill—執(zhí)行—驗(yàn)證的循環(huán)天然就是多輪的。這也是為什么 skills CLI 這類工具會(huì)出現(xiàn)。手動(dòng)管理幾十個(gè) skill 文件夾、還要保證它們被正確加載太容易出錯(cuò)了。CLI 的作用就是把安裝、更新、列出、移除 skill這些操作標(biāo)準(zhǔn)化讓 skill 的分發(fā)像裝 npm 包一樣簡(jiǎn)單。3. 核心細(xì)節(jié)解析與實(shí)操要點(diǎn)3.1 SKILL.md 到底該怎么寫這是整個(gè)體系里最容易被低估的部分。很多人第一次寫 SKILL.md會(huì)寫成一段泛泛的你要認(rèn)真寫測(cè)試之類的廢話。代理拿到這種指令跟沒(méi)拿到差不多。有效的寫法是把流程拆成可驗(yàn)證的步驟每一步都有明確的輸入和輸出。以 test-driven-development 這個(gè) skill 為例一份能用的 SKILL.md 大致包含這些內(nèi)容觸發(fā)條件當(dāng)用戶要求新增功能、修復(fù) bug、或重構(gòu)現(xiàn)有代碼時(shí)啟用前置檢查確認(rèn)項(xiàng)目里已有測(cè)試框架確認(rèn)測(cè)試命令是什么執(zhí)行流程先寫一個(gè)會(huì)失敗的測(cè)試運(yùn)行確認(rèn)它確實(shí)失敗再寫最小實(shí)現(xiàn)讓它通過(guò)最后重構(gòu)驗(yàn)證標(biāo)準(zhǔn)所有測(cè)試通過(guò)且新增測(cè)試確實(shí)覆蓋了目標(biāo)行為禁止事項(xiàng)不允許在沒(méi)寫測(cè)試的情況下直接改實(shí)現(xiàn)代碼注意最后那條禁止事項(xiàng)。這是 skill 和普通提示詞最大的區(qū)別之一——好的 skill 會(huì)明確劃出紅線。模型在沒(méi)有約束的時(shí)候傾向于走捷徑你告訴它必須先寫測(cè)試它可能還是會(huì)先寫實(shí)現(xiàn)再補(bǔ)測(cè)試。但如果你明確寫禁止先改實(shí)現(xiàn)它在多數(shù)情況下會(huì)遵守。3.2 腳本與代理的分工邊界一個(gè)常見(jiàn)的困惑是哪些事該讓代理用自然語(yǔ)言推理完成哪些事該寫成腳本讓代理調(diào)用我的經(jīng)驗(yàn)法則是確定性的、重復(fù)性的、容易出錯(cuò)的操作用腳本需要判斷和權(quán)衡的操作用自然語(yǔ)言。比如運(yùn)行測(cè)試并返回結(jié)果這件事寫成腳本最穩(wěn)因?yàn)槊钍枪潭ǖ拇碇恍枰x輸出。判斷這個(gè)測(cè)試是否覆蓋了邊界條件這件事就得靠代理推理寫不成腳本。在 agent-skills 里腳本通常放在scripts/目錄下SKILL.md 里用相對(duì)路徑引用。這樣設(shè)計(jì)的好處是腳本可以被單獨(dú)測(cè)試——你可以不啟動(dòng)代理直接跑一遍腳本看它是否正常工作。這一點(diǎn)在排查問(wèn)題時(shí)特別有用能快速區(qū)分是腳本壞了還是是代理理解錯(cuò)了。3.3 技能的粒度控制粒度太粗一個(gè) skill 管一大堆事等于沒(méi)拆粒度太細(xì)一個(gè) skill 只管一行代碼的寫法代理光加載 skill 就耗盡了上下文。我實(shí)測(cè)下來(lái)比較舒服的粒度是一個(gè) skill 對(duì)應(yīng)一個(gè)完整的、有明確起止的工作單元。寫一個(gè)函數(shù)的單元測(cè)試太細(xì)完成一個(gè)功能模塊的開(kāi)發(fā)太粗為一個(gè)已有函數(shù)補(bǔ)充測(cè)試覆蓋剛好。判斷標(biāo)準(zhǔn)很簡(jiǎn)單如果這個(gè) skill 執(zhí)行完之后你能明確說(shuō)這件事做完了那粒度就合適。3.4 版本管理與團(tuán)隊(duì)協(xié)作skill 是要演進(jìn)的。今天你覺(jué)得先寫測(cè)試這條規(guī)則沒(méi)問(wèn)題明天可能發(fā)現(xiàn)某些場(chǎng)景下需要先寫接口定義。這時(shí)候就需要版本管理。agent-skills 的目錄結(jié)構(gòu)天然適合放進(jìn) Git每個(gè) skill 一個(gè)文件夾改動(dòng)通過(guò) PR 走審查。團(tuán)隊(duì)協(xié)作時(shí)有個(gè)坑要注意不同人對(duì)同一個(gè) skill 的理解可能不一樣。我見(jiàn)過(guò)一個(gè)團(tuán)隊(duì)兩個(gè)人分別改了 code-review 這個(gè) skill一個(gè)強(qiáng)調(diào)必須指出性能問(wèn)題一個(gè)強(qiáng)調(diào)不要吹毛求疵結(jié)果合并之后代理徹底懵了。解決辦法是在 SKILL.md 里明確寫出優(yōu)先級(jí)——哪些問(wèn)題必須報(bào)哪些問(wèn)題可以忽略。4. 實(shí)操過(guò)程與核心環(huán)節(jié)實(shí)現(xiàn)4.1 環(huán)境準(zhǔn)備與 skills CLI 安裝假設(shè)你已經(jīng)在 Ubuntu 或 macOS 上裝好了 Claude Code接下來(lái)裝 skills CLI。這類 CLI 工具通常通過(guò)包管理器分發(fā)具體命令以官方文檔為準(zhǔn)我這里給一個(gè)通用的流程# 確認(rèn) Node.js 環(huán)境多數(shù) skills CLI 基于 Node node -v npm -v # 全局安裝 skills CLI包名以官方為準(zhǔn) npm install -g skills-cli-package # 驗(yàn)證安裝 skills --version裝完之后第一件事是初始化一個(gè) skills 目錄skills init這個(gè)命令會(huì)在當(dāng)前目錄下創(chuàng)建skills/文件夾和一份基礎(chǔ)配置。如果你是在已有項(xiàng)目里用建議把 skills 目錄放在項(xiàng)目根目錄跟.git平級(jí)這樣代理在項(xiàng)目里工作時(shí)能直接讀到。注意如果你用的是 VS Code 里的 Claude Code 插件skills 目錄的路徑要跟插件的工作區(qū)根目錄對(duì)齊。我踩過(guò)一次坑skills 放在上層目錄插件死活讀不到排查了半小時(shí)才發(fā)現(xiàn)是工作區(qū)范圍的問(wèn)題。4.2 安裝第一個(gè) skill以 test-driven-development 為例# 從倉(cāng)庫(kù)安裝指定 skill skills install test-driven-development # 列出已安裝的 skill skills list # 查看某個(gè) skill 的詳情 skills info test-driven-development裝完之后skills/目錄下會(huì)多出一個(gè)test-driven-development/文件夾。打開(kāi)里面的 SKILL.md 通讀一遍這一步別跳過(guò)——你得知道代理接下來(lái)會(huì)按什么流程走否則出了問(wèn)題你都不知道該從哪查。4.3 在 Claude Code 里觸發(fā) skillskill 裝好了不等于代理會(huì)自動(dòng)用。觸發(fā)方式通常有兩種第一種是顯式觸發(fā)你在對(duì)話里直接說(shuō)用 test-driven-development 這個(gè) skill 來(lái)完成這個(gè)任務(wù)。這種方式最可控適合剛開(kāi)始磨合的階段。第二種是隱式觸發(fā)代理根據(jù) SKILL.md 里寫的觸發(fā)條件自己判斷。這種方式更自然但前提是你的觸發(fā)條件寫得足夠清晰。我建議新手先用顯式觸發(fā)跑通幾輪確認(rèn) skill 行為符合預(yù)期之后再放開(kāi)隱式觸發(fā)。實(shí)測(cè)下來(lái)一個(gè)完整的 TDD 流程在 Claude Code 里大概是這樣你描述需求給用戶模塊加一個(gè)郵箱格式校驗(yàn)函數(shù)代理讀取 test-driven-development skill代理先寫測(cè)試文件包含正常郵箱、缺 符號(hào)、缺域名等用例代理運(yùn)行測(cè)試確認(rèn)失敗代理寫實(shí)現(xiàn)代碼代理再次運(yùn)行測(cè)試確認(rèn)通過(guò)代理檢查是否有可重構(gòu)的地方整個(gè)過(guò)程你能在終端里看到每一步的命令和輸出。如果第 4 步代理跳過(guò)了確認(rèn)失敗直接寫實(shí)現(xiàn)說(shuō)明 skill 的約束沒(méi)生效需要回去檢查 SKILL.md 的措辭。4.4 參數(shù)與配置的取舍skills CLI 一般會(huì)提供一些配置項(xiàng)比如 skill 的加載優(yōu)先級(jí)、是否允許代理自動(dòng)安裝新 skill、腳本執(zhí)行的超時(shí)時(shí)間等。這些參數(shù)沒(méi)有標(biāo)準(zhǔn)答案取決于你的使用場(chǎng)景。配置項(xiàng)保守設(shè)置激進(jìn)設(shè)置適用場(chǎng)景自動(dòng)安裝 skill關(guān)閉開(kāi)啟個(gè)人探索 vs 團(tuán)隊(duì)規(guī)范腳本超時(shí)30 秒300 秒單元測(cè)試 vs 集成測(cè)試隱式觸發(fā)關(guān)閉開(kāi)啟磨合期 vs 熟練期腳本執(zhí)行權(quán)限需確認(rèn)自動(dòng)執(zhí)行生產(chǎn)項(xiàng)目 vs 實(shí)驗(yàn)項(xiàng)目我的建議是從保守設(shè)置起步。尤其是腳本執(zhí)行權(quán)限讓代理自動(dòng)跑命令這件事在實(shí)驗(yàn)項(xiàng)目里很爽在生產(chǎn)項(xiàng)目里就是定時(shí)炸彈。等你對(duì)某個(gè) skill 的行為完全信任了再逐步放開(kāi)。4.5 把 skill 接進(jìn)現(xiàn)有工作流skill 不是只能手動(dòng)觸發(fā)。你可以把它接進(jìn) Git hooks、CI 流程、甚至編輯器快捷鍵。比如在 pre-commit 階段自動(dòng)跑一遍 code-review skill讓代理先審一遍改動(dòng)再提交。# 示例在 pre-commit 里調(diào)用 code-review skill #!/bin/bash skills run code-review --staged if [ $? -ne 0 ]; then echo 代碼審查未通過(guò)請(qǐng)檢查代理輸出 exit 1 fi這種接法的好處是把 AI 審查變成了流程的一部分而不是靠人記得去用。壞處是如果 skill 本身有問(wèn)題會(huì)阻塞整個(gè)提交流程。所以接進(jìn) CI 之前一定要先在本地跑夠足夠的樣本。5. 常見(jiàn)問(wèn)題與排查技巧實(shí)錄5.1 代理不按 skill 流程走怎么辦這是最高頻的問(wèn)題。表現(xiàn)是skill 明明裝了代理還是按自己的習(xí)慣來(lái)。排查順序如下先確認(rèn) skill 是否真的被加載了。在 Claude Code 里問(wèn)一句你現(xiàn)在能用哪些 skill看它列出來(lái)的清單里有沒(méi)有你要的那個(gè)。如果沒(méi)有檢查 skills 目錄路徑是否正確、CLI 是否裝在了正確的環(huán)境里。如果 skill 加載了但行為不對(duì)八成是 SKILL.md 寫得不夠明確。重點(diǎn)檢查三處觸發(fā)條件是否寫得太寬泛導(dǎo)致代理覺(jué)得這個(gè)任務(wù)不適用、執(zhí)行步驟是否有歧義導(dǎo)致代理自由發(fā)揮、禁止事項(xiàng)是否缺失導(dǎo)致代理走捷徑。我遇到過(guò)一個(gè)典型案例skill 里寫應(yīng)該先寫測(cè)試代理理解成可以最后補(bǔ)測(cè)試。把應(yīng)該改成必須把先寫測(cè)試改成在修改任何實(shí)現(xiàn)代碼之前必須先創(chuàng)建對(duì)應(yīng)的測(cè)試文件并運(yùn)行確認(rèn)其失敗問(wèn)題就解決了。給代理寫指令措辭的確定性比文采重要一百倍。5.2 腳本執(zhí)行失敗的排查路徑腳本失敗通常分三類環(huán)境問(wèn)題、權(quán)限問(wèn)題、邏輯問(wèn)題。環(huán)境問(wèn)題最常見(jiàn)比如腳本里用了python3但系統(tǒng)只有python或者依賴的某個(gè)命令行工具沒(méi)裝。排查方法是脫離代理直接在終端里手動(dòng)跑一遍腳本看報(bào)什么錯(cuò)。權(quán)限問(wèn)題在 macOS 和 Ubuntu 上表現(xiàn)不同。Ubuntu 上可能是文件沒(méi)有執(zhí)行權(quán)限chmod x一下就好。macOS 上可能是 Gatekeeper 攔截需要在系統(tǒng)設(shè)置里放行。邏輯問(wèn)題最麻煩因?yàn)槟_本本身能跑但結(jié)果不對(duì)。這時(shí)候要看腳本的輸入輸出是否符合預(yù)期。我習(xí)慣在腳本開(kāi)頭加一行set -e讓它在任何一步失敗時(shí)立即退出而不是帶著錯(cuò)誤狀態(tài)繼續(xù)往下跑。5.3 常見(jiàn)問(wèn)題速查表現(xiàn)象可能原因排查動(dòng)作代理完全無(wú)視 skillskill 未加載或路徑錯(cuò)誤詢問(wèn)代理可用 skill 列表代理部分遵循 skillSKILL.md 措辭模糊檢查觸發(fā)條件和步驟描述腳本報(bào) command not found依賴工具未安裝手動(dòng)執(zhí)行腳本看報(bào)錯(cuò)腳本無(wú)輸出權(quán)限不足或路徑錯(cuò)誤檢查執(zhí)行權(quán)限和相對(duì)路徑測(cè)試通過(guò)但結(jié)果不對(duì)測(cè)試用例覆蓋不足審查測(cè)試文件內(nèi)容skill 之間行為沖突多個(gè) skill 觸發(fā)條件重疊明確各 skill 的優(yōu)先級(jí)5.4 幾個(gè)我踩過(guò)的坑第一個(gè)坑是skill 裝太多。剛開(kāi)始新鮮一口氣裝了十幾個(gè)結(jié)果代理每次都要在眾多 skill 里挑反而變慢了還經(jīng)常挑錯(cuò)。后來(lái)精簡(jiǎn)到五六個(gè)核心 skill效率明顯提升。skill 不是越多越好夠用就行。第二個(gè)坑是忽略 skill 的更新。skill 倉(cāng)庫(kù)是會(huì)迭代的早期版本可能有 bug 或者措辭不當(dāng)。定期跑一下skills update能省不少事。但更新前記得看一眼 changelog有次更新改了一個(gè) skill 的觸發(fā)條件導(dǎo)致我原來(lái)的工作流全亂了。第三個(gè)坑是在 skill 里寫死項(xiàng)目路徑。這種 skill 換個(gè)項(xiàng)目就用不了。正確做法是用相對(duì)路徑或者環(huán)境變量讓 skill 保持可移植。第四個(gè)坑是把 skill 當(dāng)成萬(wàn)能藥。有些任務(wù)就是不適合用 skill 固化流程比如探索性的原型開(kāi)發(fā)你根本不知道下一步要做什么硬套 skill 反而束手束腳。skill 適合的是那些流程明確、重復(fù)性高的任務(wù)。5.5 關(guān)于模型選擇的補(bǔ)充Claude Code 本身支持接入不同的模型后端社區(qū)里也有各種切換方案。我的經(jīng)驗(yàn)是skill 的效果跟模型能力高度相關(guān)。同一個(gè) test-driven-development skill在能力強(qiáng)的模型上能完整走完流程在能力弱的模型上可能走到第三步就忘了前面的約束。所以如果你發(fā)現(xiàn) skill 行為不穩(wěn)定先別急著改 skill換個(gè)模型試試。如果換模型之后就好了那問(wèn)題在模型不在 skill。反過(guò)來(lái)如果換什么模型都不行那大概率是 SKILL.md 本身有問(wèn)題。另外不同模型對(duì)指令格式的敏感度不一樣。有的模型對(duì) Markdown 結(jié)構(gòu)響應(yīng)好有的對(duì)純文本段落響應(yīng)好。SKILL.md 用 Markdown 寫是通用做法但如果你的模型表現(xiàn)異?？梢栽囋嚢殃P(guān)鍵指令用純文本再?gòu)?qiáng)調(diào)一遍。6. 把 agent-skills 用出價(jià)值的幾個(gè)思路skill 體系真正的價(jià)值不在于單個(gè) skill 有多強(qiáng)而在于組合。我現(xiàn)在的做法是把幾個(gè)基礎(chǔ) skill 串成一條流水線接到需求先用一個(gè)需求澄清skill 把模糊描述變成明確任務(wù)再用 test-driven-development 寫實(shí)現(xiàn)最后用 code-review 過(guò)一遍。三個(gè) skill 各管一段代理在每段里的行為都可預(yù)測(cè)。這套組合用下來(lái)最大的感受是可預(yù)測(cè)性比峰值能力更重要。一個(gè)偶爾寫出驚艷代碼但經(jīng)常跑偏的代理不如一個(gè)每次都穩(wěn)定輸出合格代碼的代理。skill 的作用就是把代理的行為收斂到一個(gè)可接受的范圍內(nèi)犧牲一點(diǎn)上限換來(lái)大量的確定性。如果你剛開(kāi)始接觸這套東西我的建議是從一個(gè) skill 開(kāi)始把它用熟、用透理解它為什么這么設(shè)計(jì)再考慮加第二個(gè)。貪多嚼不爛這件事在 skill 體系里體現(xiàn)得特別明顯。等你對(duì)某個(gè) skill 的行為完全有把握了再把它接進(jìn)自動(dòng)化流程那時(shí)候你才真正擁有了一個(gè)可靠的 AI 編碼伙伴而不是一個(gè)需要時(shí)刻盯著的不確定因素。