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