戰(zhàn)：打造代碼審查、測(cè)試生成與提交規(guī)范)
不知道你有沒(méi)有過(guò)這樣的體驗(yàn)裝上 Claude Code 之后聊聊天、改改小文件都挺順手但一碰到稍微復(fù)雜一點(diǎn)的項(xiàng)目就感覺(jué)它“差點(diǎn)意思”。其實(shí)問(wèn)題大概率不在模型而在工作流。Claude Code 真正的優(yōu)勢(shì)不是“把對(duì)話(huà)生成代碼”而是它作為一個(gè)終端里的 AI 編程代理Agent可以被高度定制。而定制的關(guān)鍵入口就是 Skill也就是社區(qū)里常說(shuō)的“插件”“技能包”。這一期我們不聊 API 文檔也不灌概念直接講一個(gè)可落地的組合方案Claude Code 的三個(gè)實(shí)用 Skill 如何裝、如何寫(xiě)、如何搭配讓它在日常開(kāi)發(fā)里真正扛起“代碼審查、測(cè)試生成、提交整理”這三類(lèi)高頻臟活。讀完之后你會(huì)有一個(gè)可以直接復(fù)制到倉(cāng)庫(kù)里的.claude/skills目錄以及一套能長(zhǎng)期維護(hù)的 Skill 寫(xiě)法。1. 這篇文章真正要解決的問(wèn)題很多人接觸 Claude Code都是從“在終端里問(wèn)它問(wèn)題”開(kāi)始的。這種用法不能說(shuō)錯(cuò)但效率天花板很低。原因在于普通聊天式 AI 是“你說(shuō)一句它回一句”它記不住你的項(xiàng)目規(guī)范也不知道你團(tuán)隊(duì)的代碼風(fēng)格更不會(huì)主動(dòng)按你的標(biāo)準(zhǔn)去審查代碼。每次都要把背景重新交代一遍時(shí)間一長(zhǎng)人就會(huì)煩。Skill 解決的是另外一個(gè)層次的問(wèn)題把“你希望 AI 怎么做”變成一份可復(fù)用的說(shuō)明書(shū)。你寫(xiě)好一個(gè) Skill 文件Claude Code 會(huì)在合適的場(chǎng)景下自動(dòng)讀取它按照里面定義的步驟來(lái)執(zhí)行任務(wù)。這個(gè)機(jī)制很像給 AI 寫(xiě) SOP也像把團(tuán)隊(duì)的新人培訓(xùn)手冊(cè)裝進(jìn)了編輯器。這篇文章要解決的核心痛點(diǎn)有三個(gè)不知道怎么開(kāi)始Skill 目錄建在哪、文件叫什么、內(nèi)容寫(xiě)什么很多人卡在第一步。不知道怎么寫(xiě)才有效寫(xiě)了一個(gè) SKILL.md 但 Claude 不調(diào)用或者調(diào)用后效果很弱大多是因?yàn)?description 和正文結(jié)構(gòu)寫(xiě)得有問(wèn)題。不知道如何組合單個(gè) Skill 能提升一點(diǎn)效率但組合起來(lái)才能形成完整工作流。比如提交代碼前先審查、審查完后補(bǔ)測(cè)試、最后生成規(guī)范的 commit message這本來(lái)就是一個(gè)開(kāi)發(fā)閉環(huán)。所以這篇內(nèi)容更適合誰(shuí)如果你已經(jīng)裝過(guò) Claude Code但感覺(jué)沒(méi)發(fā)揮出真正價(jià)值或者你是團(tuán)隊(duì)里負(fù)責(zé)引入 AI 工具的人想讓 AI 編程真正“按團(tuán)隊(duì)規(guī)范”走而不是靠人肉提示詞那這篇文章值得你完整看完。2. Claude Code、Skill 與 Agent三個(gè)容易混淆的概念在動(dòng)手寫(xiě) Skill 之前先把三個(gè)高頻詞講清楚。它們經(jīng)常被混著說(shuō)但實(shí)際是不同層次的概念。2.1 Claude Code 是一個(gè)終端 AgentClaude Code 是 Anthropic 推出的命令行 AI 編程工具。它不是一個(gè)普通的對(duì)話(huà)窗口而是一個(gè)能感知項(xiàng)目上下文、執(zhí)行工具調(diào)用、讀寫(xiě)文件、運(yùn)行命令的代理程序。你可以在 VSCode 的終端里啟動(dòng)它也可以直接在各系統(tǒng)終端里使用。它最核心的特點(diǎn)是“能動(dòng)手”不僅會(huì)建議你改哪一行還能直接修改文件、運(yùn)行測(cè)試、查看結(jié)果。2.2 Skill 是給 Agent 的“技能說(shuō)明書(shū)”Skill 官方稱(chēng)之為“Skills”社區(qū)里常叫“插件”“技能包”。它的物理形態(tài)就是一個(gè)文件夾加一個(gè) Markdown 文件。你可以把它理解為給 Claude Code 準(zhǔn)備的一份“崗位說(shuō)明書(shū)”里面寫(xiě)清楚這個(gè)技能什么時(shí)候觸發(fā)、按什么步驟執(zhí)行、輸出什么格式。Skill 與提示詞的區(qū)別在于提示詞是一次性的需要你每次手動(dòng)輸入Skill 是持久化的它掛在項(xiàng)目目錄或用戶(hù)目錄下Claude 會(huì)根據(jù)任務(wù)內(nèi)容在合適的時(shí)機(jī)自動(dòng)參考這些說(shuō)明。用一句不嚴(yán)謹(jǐn)?shù)糜浀脑?huà)來(lái)說(shuō)提示詞是在“問(wèn)問(wèn)題”Skill 是在“定規(guī)矩”。2.3 Agent 是執(zhí)行者Skill 是能力模塊Agent 本身是一個(gè)主體它負(fù)責(zé)理解任務(wù)、調(diào)用工具、決定下一步動(dòng)作。Skill 則是給 Agent 注入的“能力模塊”。一個(gè) Agent 可以加載多個(gè) Skill就像一名工程師同時(shí)掌握代碼審查、測(cè)試編寫(xiě)和 Git 規(guī)范整理三種能力。Skill 之間還能互相配合這就是“組合插件”的含義。2.4 對(duì)比普通對(duì)話(huà)、Agent、Skill 的邊界維度普通對(duì)話(huà)式 AIClaude Code AgentClaude Code Skill是否感知項(xiàng)目上下文否是是是否自動(dòng)執(zhí)行操作否是是是否記住團(tuán)隊(duì)規(guī)范否弱強(qiáng)是否需要重復(fù)交代背景每次都要部分需要不需要可復(fù)用性低中高看完這張表你應(yīng)該能理解一個(gè)判斷如果只把 Claude Code 當(dāng)聊天框用那你用的是它最淺的一層能力只有開(kāi)始寫(xiě) Skill才真正進(jìn)入“用 AI 搭建工程流水線(xiàn)”的階段。3. 環(huán)境準(zhǔn)備與前置條件這一節(jié)我們先保證 Claude Code 能跑起來(lái)再進(jìn)入 Skill 部分。版本信息以你安裝時(shí)的官方文檔為準(zhǔn)這里演示的是通用思路。3.1 基礎(chǔ)環(huán)境Node.js 與 npmClaude Code 目前主要通過(guò) npm 分發(fā)因此需要 Node.js 環(huán)境。建議使用 Node.js 18 及以上版本低于這個(gè)版本時(shí)很多新版功能可能無(wú)法正常工作。檢查命令node -v npm -v如果還沒(méi)有安裝 Node.js可以去 Node.js 官方站點(diǎn)下載 LTS 版本或者使用 nvm 這類(lèi)版本管理工具安裝。nvm 的好處是可以在多個(gè) Node 版本之間切換不會(huì)污染全局環(huán)境。3.2 安裝 Claude Code全局安裝的命令npm install -g anthropic-ai/claude-code安裝完成后檢查版本claude --version如果能正常輸出版本號(hào)說(shuō)明安裝成功。如果提示claude: command not found大概率是 npm 的全局 bin 目錄沒(méi)有加入系統(tǒng) PATH后面常見(jiàn)問(wèn)題里會(huì)展開(kāi)講。3.3 登錄與鑒權(quán)首次運(yùn)行需要在終端執(zhí)行claude彈窗界面會(huì)引導(dǎo)你完成登錄。在生產(chǎn)環(huán)境中更推薦使用 API Key 方式便于在服務(wù)器或 CI 環(huán)境里使用export ANTHROPIC_API_KEY你的密鑰這里要提醒一句密鑰屬于敏感信息不要把它寫(xiě)進(jìn)項(xiàng)目代碼或提交到 Git 倉(cāng)庫(kù)。團(tuán)隊(duì)協(xié)作時(shí)建議使用環(huán)境變量管理工具或密鑰管理服務(wù)。3.4 網(wǎng)絡(luò)受限環(huán)境的安裝策略如果你所在網(wǎng)絡(luò)環(huán)境訪(fǎng)問(wèn) npm 或 GitHub 不穩(wěn)定安裝可能會(huì)卡住。這種情況下的處理方式和“下載慢”還不完全一樣可以從三個(gè)方向優(yōu)先嘗試切換 npm 鏡像源使用國(guó)內(nèi)可訪(fǎng)問(wèn)的 registry。優(yōu)先使用 npm 包方式安裝避免直接下載 GitHub 倉(cāng)庫(kù)壓縮包。如果項(xiàng)目依賴(lài)來(lái)自 GitHub可以找項(xiàng)目是否提供了 npm 包或鏡像倉(cāng)庫(kù)地址。這些都屬于常規(guī)的依賴(lài)獲取問(wèn)題不要因此下載來(lái)源不明的“加速工具”或“綠色版安裝包”。另外如果你當(dāng)前使用的模型端點(diǎn)和 Community 實(shí)驗(yàn)配置和官方模型名不對(duì)應(yīng)后續(xù)也會(huì)出現(xiàn)模型識(shí)別問(wèn)題這一點(diǎn)在第 7 節(jié)的排查表里會(huì)專(zhuān)門(mén)說(shuō)明。4. Skill 的核心機(jī)制與目錄規(guī)范安裝好 Claude Code 之后下一步就是理解 Skill 的存放位置和文件規(guī)范。4.1 項(xiàng)目級(jí) Skill 目錄最常用的是項(xiàng)目級(jí) Skill。在項(xiàng)目根目錄下創(chuàng)建一個(gè).claude/skills目錄里面每個(gè)子目錄就是一個(gè) Skill。結(jié)構(gòu)如下你的項(xiàng)目/ └── .claude/ ├── CLAUDE.md ├── settings.json └── skills/ ├── code-review/ │ └── SKILL.md ├── test-writer/ │ └── SKILL.md └── commit-helper/ └── SKILL.md.claude/CLAUDE.md項(xiàng)目級(jí)記憶文件。用來(lái)寫(xiě)團(tuán)隊(duì)的長(zhǎng)期約定比如“本項(xiàng)目使用 TypeScript”“提交信息必須符合 Conventional Commits”。Claude 每次任務(wù)都會(huì)參考它。.claude/settings.json工具權(quán)限控制文件?？梢韵拗?Claude 能執(zhí)行的命令范圍屬于安全邊界的一部分。.claude/skills/skill-name/SKILL.md每個(gè) Skill 的核心內(nèi)容。4.2 SKILL.md 的文件格式SKILL.md 分為兩部分開(kāi)頭的 YAML frontmatter以及正文的 Markdown 指令。--- name: skill-name description: 在什么時(shí)候、什么場(chǎng)景下使用這個(gè) Skill --- 這里是具體的執(zhí)行步驟和規(guī)則。frontmatter 里兩個(gè)字段最關(guān)鍵nameSkill 的名字一般用小寫(xiě)字母加連字符。這個(gè)名字會(huì)用于調(diào)用和日志展示。descriptionClaude 判斷“什么時(shí)候該用這個(gè) Skill”的依據(jù)。這句話(huà)寫(xiě)得越具體Skill 被正確觸發(fā)的概率越高。4.3 description 怎么寫(xiě)才不會(huì)被“無(wú)視”很多人寫(xiě)完 Skill 后發(fā)現(xiàn) Claude 壓根不調(diào)用問(wèn)題幾乎都出在 description 上。description 需要滿(mǎn)足三個(gè)條件以動(dòng)詞開(kāi)頭明確指出觸發(fā)動(dòng)作比如“當(dāng)需要審查代碼時(shí)使用”“當(dāng)需要生成單元測(cè)試時(shí)使用”。寫(xiě)清楚適用對(duì)象比如“針對(duì) Python 函數(shù)”“針對(duì)當(dāng)前 Pull Request 的改動(dòng)”。不要寫(xiě)成模糊的“幫我做事”而要寫(xiě)成“遇到這類(lèi)需求時(shí)讀取并遵循此 Skill 的規(guī)則”。下面是一個(gè)反例和一個(gè)正例反例description: 代碼審查技能用于提升代碼質(zhì)量。正例description: 當(dāng)用戶(hù)要求審查代碼、檢查 PR、或評(píng)估代碼質(zhì)量和安全隱患時(shí)使用。按安全、性能、可讀性、測(cè)試覆蓋四個(gè)維度輸出結(jié)論。區(qū)別很明顯反例像一句口號(hào)Claude 無(wú)法判斷什么時(shí)候觸發(fā)正例給出了明確的觸發(fā)條件和輸出方式。4.4 項(xiàng)目級(jí)與用戶(hù)級(jí) Skill項(xiàng)目級(jí) Skill 放在倉(cāng)庫(kù)目錄下最適合團(tuán)隊(duì)共享。因?yàn)橐坏┨峤坏?Git所有克隆倉(cāng)庫(kù)的成員都會(huì)拿到這套規(guī)范新人入職看到.claude目錄就能立刻了解團(tuán)隊(duì)對(duì) AI 的使用約定。如果你有自己固定的一套通用 Skill不想每個(gè)項(xiàng)目重復(fù)粘貼也可以放在用戶(hù)級(jí)目錄下。具體路徑在不同版本中可能不同建議安裝后查看官方文檔。更穩(wěn)妥的判斷是通用能力放用戶(hù)級(jí)項(xiàng)目相關(guān)規(guī)范放項(xiàng)目級(jí)。例如“提交信息規(guī)范”通常適合放項(xiàng)目級(jí)因?yàn)槊總€(gè)團(tuán)隊(duì)的提交規(guī)范不一定相同而“通用代碼審查模板”這種不依賴(lài)具體語(yǔ)言的可以放用戶(hù)級(jí)。5. 三個(gè)實(shí)用 Skill 組合實(shí)戰(zhàn)這一節(jié)是全文的重頭。我們直接用命令創(chuàng)建一個(gè)可用的 Skill 組合然后逐個(gè)解釋 SKILL.md 的內(nèi)容。5.1 創(chuàng)建目錄骨架在項(xiàng)目根目錄下執(zhí)行mkdir -p .claude/skills/code-review mkdir -p .claude/skills/test-writer mkdir -p .claude/skills/commit-helper如果是在 Windows 上使用 CMD可以用mkdir .claude\skills\code-review mkdir .claude\skills\test-writer mkdir .claude\skills\commit-helper創(chuàng)建完成后目錄結(jié)構(gòu)應(yīng)該和 4.1 節(jié)展示的一致。5.2 Skill 1code-review把代碼審查變成標(biāo)準(zhǔn)動(dòng)作先創(chuàng)建.claude/skills/code-review/SKILL.md內(nèi)容如下--- name: code-review description: 當(dāng)用戶(hù)要求審查代碼、檢查代碼質(zhì)量、評(píng)估 PR 或查看某個(gè)文件的安全風(fēng)險(xiǎn)時(shí)使用。按安全、性能、可讀性、測(cè)試覆蓋四個(gè)維度輸出結(jié)論。 --- # Code Review Skill 請(qǐng)按以下流程審查代碼 1. 先讀取目標(biāo)文件分析代碼改動(dòng)范圍。 2. 按四個(gè)維度輸出結(jié)論 - 安全性注入風(fēng)險(xiǎn)、權(quán)限校驗(yàn)、敏感信息泄露、依賴(lài)安全問(wèn)題。 - 性能不必要的循環(huán)、重復(fù)請(qǐng)求、內(nèi)存使用、IO 開(kāi)銷(xiāo)。 - 可讀性與維護(hù)性命名、函數(shù)長(zhǎng)度、重復(fù)代碼、模塊劃分。 - 測(cè)試覆蓋是否有對(duì)應(yīng)測(cè)試、邊界條件是否覆蓋、異常路徑是否處理。 3. 每個(gè)問(wèn)題標(biāo)注嚴(yán)重級(jí)別嚴(yán)重必須改/ 建議應(yīng)該改/ 提醒可選優(yōu)化。 4. 不要輸出空泛評(píng)價(jià)所有意見(jiàn)必須能落到具體代碼位置。 輸出模板 ## 審查結(jié)論 整體質(zhì)量?jī)?yōu) / 良 / 需改進(jìn) ### 嚴(yán)重問(wèn)題 ### 建議問(wèn)題 ### 可選優(yōu)化這個(gè) Skill 的價(jià)值在于它把“代碼審查”從一個(gè)模糊的對(duì)話(huà)請(qǐng)求變成了一套固定輸出格式。你不需要每次告訴 Claude“你要從哪幾個(gè)維度看”它自己會(huì)按模板來(lái)。5.3 Skill 2test-writer把測(cè)試生成變成流程第二個(gè) Skill 用于生成單元測(cè)試。創(chuàng)建.claude/skills/test-writer/SKILL.md--- name: test-writer description: 當(dāng)用戶(hù)要求為某個(gè)函數(shù)、類(lèi)或接口補(bǔ)充單元測(cè)試時(shí)使用。支持 Python、TypeScript、Java 等主流語(yǔ)言自動(dòng)匹配項(xiàng)目使用的測(cè)試框架。 --- # Test Writer Skill 1. 先分析目標(biāo)模塊的輸入、輸出和邊界條件。 2. 根據(jù)項(xiàng)目語(yǔ)言選擇測(cè)試框架 - Pythonpytest - TypeScript / JavaScriptVitest 或 Jest - JavaJUnit 5 3. 輸出測(cè)試文件路徑和完整測(cè)試代碼。 4. 測(cè)試用例必須覆蓋 - 正常輸入路徑。 - 空值、越界、非法參數(shù)等邊界情況。 - 預(yù)期拋出異常的異常路徑。 5. 如果項(xiàng)目已有測(cè)試風(fēng)格優(yōu)先保持風(fēng)格一致。 6. 生成結(jié)束后給出當(dāng)前項(xiàng)目運(yùn)行測(cè)試的命令。這里有一個(gè)容易踩的坑Claude 默認(rèn)生成測(cè)試代碼時(shí)可能不會(huì)先檢查項(xiàng)目已有的測(cè)試風(fēng)格。如果你在description里不強(qiáng)調(diào)“保持項(xiàng)目風(fēng)格一致”它有時(shí)會(huì)生成一個(gè)寫(xiě)法完全不同的測(cè)試文件雖然能跑但會(huì)讓維護(hù)者很頭疼。加入第 5 條之后Claude 會(huì)先看項(xiàng)目里已有的測(cè)試文件再動(dòng)手。5.4 Skill 3commit-helper把 Git 提交信息變成規(guī)范第三個(gè) Skill 負(fù)責(zé) Git 提交信息。創(chuàng)建.claude/skills/commit-helper/SKILL.md--- name: commit-helper description: 當(dāng)用戶(hù)準(zhǔn)備提交代碼、需要編寫(xiě) git commit message、或整理 CHANGELOG 時(shí)使用。將根據(jù)項(xiàng)目改動(dòng)生成規(guī)范提交信息。 --- # Commit Helper Skill 1. 使用 git status 和 git diff --stat 查看本次改動(dòng)文件。 2. 閱讀有代表性的 diff理解改動(dòng)意圖。 3. 按照 Conventional Commits 規(guī)范生成提交信息 type(scope): subject type 取值范圍 - feat新功能 - fix修復(fù)問(wèn)題 - docs文檔變更 - style格式調(diào)整 - refactor重構(gòu) - perf性能優(yōu)化 - test測(cè)試相關(guān) - chore構(gòu)建、依賴(lài)等雜項(xiàng) 4. 將提交信息展示給用戶(hù)獲得確認(rèn)后再建議執(zhí)行 git commit。 5. 不要擅自提交代碼除非用戶(hù)明確授權(quán)。很多人會(huì)覺(jué)得提交信息一個(gè)git commit -m fix bug就夠了沒(méi)必要交給 AI。但實(shí)際上在多分支協(xié)作或需要生成 CHANGELOG 的項(xiàng)目里提交信息的規(guī)范性直接影響后續(xù)的自動(dòng)化發(fā)布和版本追溯。如果團(tuán)隊(duì)準(zhǔn)備接語(yǔ)義化版本發(fā)布流程這一條 Skill 的價(jià)值會(huì)立刻體現(xiàn)。5.5 用 CLAUDE.md 把三個(gè) Skill 串起來(lái)三個(gè) Skill 單獨(dú)用都有效但組合起來(lái)才更像“一條流水線(xiàn)”。這個(gè)組合的關(guān)鍵是在.claude/CLAUDE.md里定義固定順序// .claude/CLAUDE.md 團(tuán)隊(duì)開(kāi)發(fā)約定 1. 修改代碼后先運(yùn)行 test-writer 生成或補(bǔ)充單元測(cè)試。 2. 提交代碼前使用 code-review 完成一次審查。 3. 最終提交時(shí)使用 commit-helper 生成規(guī)范提交信息。 4. 涉及破壞性變更時(shí)必須同時(shí)給出回滾方案。CLAUDE.md 的作用是“長(zhǎng)期記憶”。Claude 在每次執(zhí)行任務(wù)時(shí)都會(huì)參考它所以它會(huì)知道“這個(gè)團(tuán)隊(duì)要求先補(bǔ)測(cè)試、再審查、最后規(guī)范提交”。三個(gè) Skill 就不再是孤立的提示詞而是被統(tǒng)一到一個(gè)工作流里。5.6 交互式調(diào)用示例啟動(dòng) Claude Codeclaude在交互界面中輸入code-review 審查 src/main.py或者一次性做多步請(qǐng)為 utils/date.py 生成單元測(cè)試然后審查一下測(cè)試代碼。如果你希望跳過(guò)交互直接以非交互方式執(zhí)行可以用claude -p test-writer 為 utils/date.py 生成 pytest 用例這種非交互方式適合在腳本中調(diào)用后面驗(yàn)證時(shí)會(huì)用到。6. 運(yùn)行效果與驗(yàn)證方法Skill 配好后怎么判斷它是真的生效而不是假裝生效這一節(jié)給出可執(zhí)行的驗(yàn)證步驟。6.1 驗(yàn)證 Skill 目錄被識(shí)別在 Claude Code 交互界面中輸入斜杠命令查看當(dāng)前會(huì)話(huà)可用的技能列表。/help或者直接輸入 Skill 名看是否有補(bǔ)全提示code-review如果輸入后能看到code-review、test-writer、commit-helper三個(gè)選項(xiàng)說(shuō)明 Skill 已經(jīng)被加載。6.2 用一個(gè)最小函數(shù)驗(yàn)證 code-review先創(chuàng)建一個(gè)測(cè)試文件# 文件路徑src/example.py def get_user_name(user_id, db): sql SELECT name FROM users WHERE id user_id return db.execute(sql)然后在 Claude Code 中調(diào)用code-review 審查 src/example.py預(yù)期輸出中應(yīng)該包含四個(gè)維度安全性SQL 注入風(fēng)險(xiǎn)、性能無(wú)大問(wèn)題但建議使用參數(shù)化查詢(xún)、可讀性函數(shù)命名沒(méi)問(wèn)題但缺少類(lèi)型注解、測(cè)試覆蓋缺少測(cè)試。如果輸出只是“代碼寫(xiě)得不錯(cuò)”這類(lèi)評(píng)價(jià)說(shuō)明 Skill 的正文沒(méi)有被正確讀取需要檢查 frontmatter。6.3 驗(yàn)證 test-writer繼續(xù)用上面這個(gè)例子claude -p test-writer 為 src/example.py 生成 pytest 測(cè)試預(yù)期輸出會(huì)包含一個(gè)test_example.py的代碼塊并且至少覆蓋正常路徑和異常路徑。你可以把生成的代碼保存下來(lái)用 pytest 手動(dòng)運(yùn)行確認(rèn)。6.4 驗(yàn)證 commit-helper在項(xiàng)目工作區(qū)做一次改動(dòng)后調(diào)用commit-helper 幫我生成提交信息預(yù)期輸出是一行類(lèi)似下面的信息fix(users): 使用參數(shù)化查詢(xún)修復(fù)用戶(hù)查詢(xún)的 SQL 注入風(fēng)險(xiǎn)如果沒(méi)有生成這種格式而是給了一堆廢話(huà)說(shuō)明 SKILL.md 中的模板沒(méi)有被遵循或者當(dāng)前版本對(duì) Markdown 指令的理解方式和你預(yù)期不同可以適當(dāng)把步驟寫(xiě)得更短、更指令化。6.5 失敗時(shí)的第一排查順序如果運(yùn)行結(jié)果不符合預(yù)期不要急著改內(nèi)容先按順序查目錄名和文件名是否完全正確必須是.claude/skills/skill-name/SKILL.md。frontmatter 是否使用了---包裹。description是否準(zhǔn)確描述了當(dāng)前任務(wù)場(chǎng)景。是否調(diào)用了正確的 Skill 名。當(dāng)前 Claude Code 版本是否過(guò)舊舊版本可能不支持新加的 Skill 功能。7. 常見(jiàn)問(wèn)題與排查思路下面把實(shí)際使用中最高頻的問(wèn)題整理成一張排查表。問(wèn)題現(xiàn)象可能原因排查方式解決方案claude: command not foundnpm 全局 bin 目錄不在 PATH 中執(zhí)行npm prefix -g查看全局目錄將該目錄加入系統(tǒng) PATH重開(kāi)終端Skill 明明寫(xiě)了卻不生效目錄位置寫(xiě)錯(cuò)或 SKILL.md 文件名錯(cuò)誤檢查是否在.claude/skills/name/SKILL.md按規(guī)范重建文件注意大小寫(xiě)輸入skill-name沒(méi)反應(yīng)frontmatter 缺失或解析失敗用編輯器檢查文件頭部是否被 BOM 干擾刪除 BOM確認(rèn)name字段正確Claude 不主動(dòng)調(diào)用 Skilldescription 寫(xiě)得像口號(hào)無(wú)法觸發(fā)重讀 description 是否包含觸發(fā)場(chǎng)景改成“當(dāng)用戶(hù)要求……時(shí)使用”句式生成內(nèi)容總是不符合團(tuán)隊(duì)風(fēng)格缺少項(xiàng)目級(jí)約定查看.claude/CLAUDE.md是否為空在 CLAUDE.md 中補(bǔ)充團(tuán)隊(duì)規(guī)范提示xxx is not a model this version of claude code recognizes使用了當(dāng)前版本無(wú)法識(shí)別的模型名或?qū)嶒?yàn)性配置檢查當(dāng)前claude --version版本確認(rèn)模型名恢復(fù)官方默認(rèn)模型或升級(jí) Claude Code 后再試下載安裝時(shí)進(jìn)度卡住網(wǎng)絡(luò)環(huán)境受限觀察 npm 日志和下載地址切換 npm 鏡像源重試安裝工具執(zhí)行被拒絕當(dāng)前權(quán)限配置限制了命令查看settings.json中的權(quán)限設(shè)置按最小權(quán)限原則放開(kāi)明確需要的命令生產(chǎn)環(huán)境需人工審批這里的模型名報(bào)錯(cuò)需要特別說(shuō)明這個(gè)問(wèn)題通常出現(xiàn)在用戶(hù)手動(dòng)配置了第三方模型端點(diǎn)或?qū)嶒?yàn)性模型名之后。AI 編程工具對(duì)模型名的識(shí)別和當(dāng)前版本強(qiáng)相關(guān)在沒(méi)有官方文檔明確支持的情況下不建議在生產(chǎn)環(huán)境使用未經(jīng)驗(yàn)證的模型名。穩(wěn)妥的做法是保持 Claude Code 默認(rèn)模型配置。8. 最佳實(shí)踐與工程建議Skill 寫(xiě)得好不好不是看代碼多少而是看“觸達(dá)率”和“穩(wěn)定性”。觸達(dá)率是指任務(wù)出現(xiàn)時(shí) Skill 能被正確調(diào)用的概率穩(wěn)定性是指無(wú)論 Claude 怎么理解輸出結(jié)果都能保持近似格式。下面這組建議能同時(shí)提升兩者。8.1 Skill 設(shè)計(jì)原則一個(gè) Skill 只做一件事不要把“代碼審查、寫(xiě)文檔、生成測(cè)試、處理 Git”全部塞進(jìn)一個(gè) SKILL.md。一個(gè) Skill 只負(fù)責(zé)一個(gè)職責(zé)原因有兩點(diǎn)description 更容易寫(xiě)清楚Claude 調(diào)用時(shí)會(huì)更快匹配。正文更短模型不會(huì)“讀了后半段忘了前半段”。如果發(fā)現(xiàn)一個(gè) SKILL.md 里出現(xiàn)了兩套不相關(guān)的步驟就應(yīng)該拆成兩個(gè) Skill。8.2 description 的統(tǒng)一句式推薦在這種格式中填充description: 當(dāng)用戶(hù)要求{動(dòng)作}時(shí)使用。適用于{場(chǎng)景}。輸出應(yīng)按{格式}完成。例如description: 當(dāng)用戶(hù)要求編寫(xiě)提交信息時(shí)使用。適用于正在準(zhǔn)備 git commit 的開(kāi)發(fā)者。輸出應(yīng)符合 Conventional Commits 規(guī)范。這個(gè)句式把“觸發(fā)條件、適用對(duì)象、輸出要求”三個(gè)關(guān)鍵信息都覆蓋了。8.3 把 Skill 納入版本管理.claude/skills目錄建議提交到 Git 倉(cāng)庫(kù)。這樣團(tuán)隊(duì)每個(gè)成員 Clone 后都會(huì)自動(dòng)獲得同一套技能配置不會(huì)出現(xiàn)“我本地可以、你本地不行”的情況。建議在倉(cāng)庫(kù)的 README 中加一節(jié)說(shuō)明## AI 輔助開(kāi)發(fā) 本倉(cāng)庫(kù)使用 Claude Code 作為 AI 編程輔助工具。 - 代碼審查code-review - 單元測(cè)試test-writer - 提交信息commit-helper8.4 安全邊界讓 AI 動(dòng)代碼前先確認(rèn)Skill 賦予了 Claude 執(zhí)行任務(wù)的能力但能力越強(qiáng)越需要邊界。建議從三個(gè)層面控制權(quán)限層通過(guò).claude/settings.json控制哪些命令允許自動(dòng)執(zhí)行哪些必須詢(xún)問(wèn)用戶(hù)。內(nèi)容層不要在 SKILL.md 中寫(xiě)入任何密鑰、內(nèi)部域名、敏感路徑和涉密信息因?yàn)樗琼?xiàng)目文件會(huì)被提交到倉(cāng)庫(kù)并共享。操作層涉及刪除文件、修改數(shù)據(jù)庫(kù)結(jié)構(gòu)、發(fā)布產(chǎn)物等危險(xiǎn)操作時(shí)讓 AI 先輸出執(zhí)行計(jì)劃等待人工確認(rèn)后再執(zhí)行。8.5 模型接入穩(wěn)定優(yōu)先平時(shí)關(guān)注 AI 編程工具的同學(xué)可能會(huì)看到社區(qū)里有人把 Claude Code 接到其他模型上實(shí)驗(yàn)。這類(lèi)玩法適合學(xué)習(xí)和研究但不建議直接引入生產(chǎn)環(huán)境。最直接的原因就是兼容性不同模型對(duì)工具調(diào)用的格式、上下文長(zhǎng)度、指令遵循程度的差異很大某個(gè)版本能用升級(jí)后可能就報(bào)“model not recognized”之類(lèi)的錯(cuò)誤。如果你真的想嘗試唯一正確的做法是在獨(dú)立環(huán)境里做實(shí)驗(yàn)使用官方文檔明確支持的模型名并且保證切換失敗時(shí)可以快速回滾默認(rèn)配置。生產(chǎn)環(huán)境保持原廠(chǎng)配置這是最穩(wěn)的選擇。8.6 Skill 的維護(hù)節(jié)奏Skill 不是寫(xiě)一次就一勞永逸的。建議在以下時(shí)刻主動(dòng)更新團(tuán)隊(duì)規(guī)范發(fā)生變化時(shí)。Claude Code 大版本升級(jí)后用現(xiàn)有 Skill 跑一遍舊任務(wù)確認(rèn)輸出沒(méi)有明顯退化。發(fā)現(xiàn) Skill 生成的輸出總是需要人工二次修改時(shí)應(yīng)該修改 Skill 正文補(bǔ)充約束而不是每次手動(dòng)糾正。9. 總結(jié)與下一步實(shí)踐這篇文章的核心脈絡(luò)可以濃縮成三句話(huà)第一Claude Code 的價(jià)值不在對(duì)話(huà)而在 Agent 能力Skill 是給它注入能力的標(biāo)準(zhǔn)方式。第二一個(gè) Skill 就是一個(gè)SKILL.md文件關(guān)鍵是寫(xiě)清楚description觸發(fā)時(shí)機(jī)和正文的執(zhí)行步驟目錄規(guī)范是.claude/skills/skill-name/SKILL.md。第三三個(gè)實(shí)用 Skill 可以組合成一條連貫的開(kāi)發(fā)流程test-writer補(bǔ)測(cè)試、code-review做審查、commit-helper保證提交規(guī)范。組合起來(lái)之后它就不再是三個(gè)孤立的提示詞而是一套可復(fù)用的團(tuán)隊(duì)工程規(guī)范。如果你剛接觸這塊建議現(xiàn)在動(dòng)手做一件最小的事在任意一個(gè)最常用的 Git 項(xiàng)目里創(chuàng)建.claude/skills/commit-helper/SKILL.md把第 5.4 節(jié)的代碼復(fù)制進(jìn)去然后下次提交代碼時(shí)試著調(diào)用一次。跑通這一個(gè)再逐步加上測(cè)試生成和代碼審查。不要一次性把十幾個(gè) Skill 全部堆進(jìn)倉(cāng)庫(kù)Skill 越多維護(hù)成本越高先用最小集跑通日常流程再按實(shí)際需要擴(kuò)充。另外給一個(gè)新入門(mén)的團(tuán)隊(duì)一個(gè)建議Skill 的引入最好和團(tuán)隊(duì)現(xiàn)有流程綁定而不是另起爐灶。比如你們已經(jīng)在用 Conventional Commits那就把 commit-helper 直接對(duì)應(yīng)到現(xiàn)有規(guī)范你們已經(jīng)有一套代碼評(píng)審檢查單那就把 code-review 的內(nèi)容改成團(tuán)隊(duì)自己的版本。這樣 AI 不是替代原有流程而是在原流程里多了一個(gè)穩(wěn)定的執(zhí)行者。過(guò)一個(gè)月回頭看你會(huì)發(fā)現(xiàn)真正有價(jià)值的不是某個(gè) Skill 的寫(xiě)法而是這套“把團(tuán)隊(duì)規(guī)范固化成 AI 可執(zhí)行指令”的思維方式。 Claude Code Skill實(shí)戰(zhàn)：打造代碼審查、測(cè)試生成與提交規(guī)范
不知道你有沒(méi)有過(guò)這樣的體驗(yàn)裝上 Claude Code 之后聊聊天、改改小文件都挺順手但一碰到稍微復(fù)雜一點(diǎn)的項(xiàng)目就感覺(jué)它“差點(diǎn)意思”。其實(shí)問(wèn)題大概率不在模型而在工作流。Claude Code 真正的優(yōu)勢(shì)不是“把對(duì)話(huà)生成代碼”而是它作為一個(gè)終端里的 AI 編程代理Agent可以被高度定制。而定制的關(guān)鍵入口就是 Skill也就是社區(qū)里常說(shuō)的“插件”“技能包”。這一期我們不聊 API 文檔也不灌概念直接講一個(gè)可落地的組合方案Claude Code 的三個(gè)實(shí)用 Skill 如何裝、如何寫(xiě)、如何搭配讓它在日常開(kāi)發(fā)里真正扛起“代碼審查、測(cè)試生成、提交整理”這三類(lèi)高頻臟活。讀完之后你會(huì)有一個(gè)可以直接復(fù)制到倉(cāng)庫(kù)里的.claude/skills目錄以及一套能長(zhǎng)期維護(hù)的 Skill 寫(xiě)法。1. 這篇文章真正要解決的問(wèn)題很多人接觸 Claude Code都是從“在終端里問(wèn)它問(wèn)題”開(kāi)始的。這種用法不能說(shuō)錯(cuò)但效率天花板很低。原因在于普通聊天式 AI 是“你說(shuō)一句它回一句”它記不住你的項(xiàng)目規(guī)范也不知道你團(tuán)隊(duì)的代碼風(fēng)格更不會(huì)主動(dòng)按你的標(biāo)準(zhǔn)去審查代碼。每次都要把背景重新交代一遍時(shí)間一長(zhǎng)人就會(huì)煩。Skill 解決的是另外一個(gè)層次的問(wèn)題把“你希望 AI 怎么做”變成一份可復(fù)用的說(shuō)明書(shū)。你寫(xiě)好一個(gè) Skill 文件Claude Code 會(huì)在合適的場(chǎng)景下自動(dòng)讀取它按照里面定義的步驟來(lái)執(zhí)行任務(wù)。這個(gè)機(jī)制很像給 AI 寫(xiě) SOP也像把團(tuán)隊(duì)的新人培訓(xùn)手冊(cè)裝進(jìn)了編輯器。這篇文章要解決的核心痛點(diǎn)有三個(gè)不知道怎么開(kāi)始Skill 目錄建在哪、文件叫什么、內(nèi)容寫(xiě)什么很多人卡在第一步。不知道怎么寫(xiě)才有效寫(xiě)了一個(gè) SKILL.md 但 Claude 不調(diào)用或者調(diào)用后效果很弱大多是因?yàn)?description 和正文結(jié)構(gòu)寫(xiě)得有問(wèn)題。不知道如何組合單個(gè) Skill 能提升一點(diǎn)效率但組合起來(lái)才能形成完整工作流。比如提交代碼前先審查、審查完后補(bǔ)測(cè)試、最后生成規(guī)范的 commit message這本來(lái)就是一個(gè)開(kāi)發(fā)閉環(huán)。所以這篇內(nèi)容更適合誰(shuí)如果你已經(jīng)裝過(guò) Claude Code但感覺(jué)沒(méi)發(fā)揮出真正價(jià)值或者你是團(tuán)隊(duì)里負(fù)責(zé)引入 AI 工具的人想讓 AI 編程真正“按團(tuán)隊(duì)規(guī)范”走而不是靠人肉提示詞那這篇文章值得你完整看完。2. Claude Code、Skill 與 Agent三個(gè)容易混淆的概念在動(dòng)手寫(xiě) Skill 之前先把三個(gè)高頻詞講清楚。它們經(jīng)常被混著說(shuō)但實(shí)際是不同層次的概念。2.1 Claude Code 是一個(gè)終端 AgentClaude Code 是 Anthropic 推出的命令行 AI 編程工具。它不是一個(gè)普通的對(duì)話(huà)窗口而是一個(gè)能感知項(xiàng)目上下文、執(zhí)行工具調(diào)用、讀寫(xiě)文件、運(yùn)行命令的代理程序。你可以在 VSCode 的終端里啟動(dòng)它也可以直接在各系統(tǒng)終端里使用。它最核心的特點(diǎn)是“能動(dòng)手”不僅會(huì)建議你改哪一行還能直接修改文件、運(yùn)行測(cè)試、查看結(jié)果。2.2 Skill 是給 Agent 的“技能說(shuō)明書(shū)”Skill 官方稱(chēng)之為“Skills”社區(qū)里常叫“插件”“技能包”。它的物理形態(tài)就是一個(gè)文件夾加一個(gè) Markdown 文件。你可以把它理解為給 Claude Code 準(zhǔn)備的一份“崗位說(shuō)明書(shū)”里面寫(xiě)清楚這個(gè)技能什么時(shí)候觸發(fā)、按什么步驟執(zhí)行、輸出什么格式。Skill 與提示詞的區(qū)別在于提示詞是一次性的需要你每次手動(dòng)輸入Skill 是持久化的它掛在項(xiàng)目目錄或用戶(hù)目錄下Claude 會(huì)根據(jù)任務(wù)內(nèi)容在合適的時(shí)機(jī)自動(dòng)參考這些說(shuō)明。用一句不嚴(yán)謹(jǐn)?shù)糜浀脑?huà)來(lái)說(shuō)提示詞是在“問(wèn)問(wèn)題”Skill 是在“定規(guī)矩”。2.3 Agent 是執(zhí)行者Skill 是能力模塊Agent 本身是一個(gè)主體它負(fù)責(zé)理解任務(wù)、調(diào)用工具、決定下一步動(dòng)作。Skill 則是給 Agent 注入的“能力模塊”。一個(gè) Agent 可以加載多個(gè) Skill就像一名工程師同時(shí)掌握代碼審查、測(cè)試編寫(xiě)和 Git 規(guī)范整理三種能力。Skill 之間還能互相配合這就是“組合插件”的含義。2.4 對(duì)比普通對(duì)話(huà)、Agent、Skill 的邊界維度普通對(duì)話(huà)式 AIClaude Code AgentClaude Code Skill是否感知項(xiàng)目上下文否是是是否自動(dòng)執(zhí)行操作否是是是否記住團(tuán)隊(duì)規(guī)范否弱強(qiáng)是否需要重復(fù)交代背景每次都要部分需要不需要可復(fù)用性低中高看完這張表你應(yīng)該能理解一個(gè)判斷如果只把 Claude Code 當(dāng)聊天框用那你用的是它最淺的一層能力只有開(kāi)始寫(xiě) Skill才真正進(jìn)入“用 AI 搭建工程流水線(xiàn)”的階段。3. 環(huán)境準(zhǔn)備與前置條件這一節(jié)我們先保證 Claude Code 能跑起來(lái)再進(jìn)入 Skill 部分。版本信息以你安裝時(shí)的官方文檔為準(zhǔn)這里演示的是通用思路。3.1 基礎(chǔ)環(huán)境Node.js 與 npmClaude Code 目前主要通過(guò) npm 分發(fā)因此需要 Node.js 環(huán)境。建議使用 Node.js 18 及以上版本低于這個(gè)版本時(shí)很多新版功能可能無(wú)法正常工作。檢查命令node -v npm -v如果還沒(méi)有安裝 Node.js可以去 Node.js 官方站點(diǎn)下載 LTS 版本或者使用 nvm 這類(lèi)版本管理工具安裝。nvm 的好處是可以在多個(gè) Node 版本之間切換不會(huì)污染全局環(huán)境。3.2 安裝 Claude Code全局安裝的命令npm install -g anthropic-ai/claude-code安裝完成后檢查版本claude --version如果能正常輸出版本號(hào)說(shuō)明安裝成功。如果提示claude: command not found大概率是 npm 的全局 bin 目錄沒(méi)有加入系統(tǒng) PATH后面常見(jiàn)問(wèn)題里會(huì)展開(kāi)講。3.3 登錄與鑒權(quán)首次運(yùn)行需要在終端執(zhí)行claude彈窗界面會(huì)引導(dǎo)你完成登錄。在生產(chǎn)環(huán)境中更推薦使用 API Key 方式便于在服務(wù)器或 CI 環(huán)境里使用export ANTHROPIC_API_KEY你的密鑰這里要提醒一句密鑰屬于敏感信息不要把它寫(xiě)進(jìn)項(xiàng)目代碼或提交到 Git 倉(cāng)庫(kù)。團(tuán)隊(duì)協(xié)作時(shí)建議使用環(huán)境變量管理工具或密鑰管理服務(wù)。3.4 網(wǎng)絡(luò)受限環(huán)境的安裝策略如果你所在網(wǎng)絡(luò)環(huán)境訪(fǎng)問(wèn) npm 或 GitHub 不穩(wěn)定安裝可能會(huì)卡住。這種情況下的處理方式和“下載慢”還不完全一樣可以從三個(gè)方向優(yōu)先嘗試切換 npm 鏡像源使用國(guó)內(nèi)可訪(fǎng)問(wèn)的 registry。優(yōu)先使用 npm 包方式安裝避免直接下載 GitHub 倉(cāng)庫(kù)壓縮包。如果項(xiàng)目依賴(lài)來(lái)自 GitHub可以找項(xiàng)目是否提供了 npm 包或鏡像倉(cāng)庫(kù)地址。這些都屬于常規(guī)的依賴(lài)獲取問(wèn)題不要因此下載來(lái)源不明的“加速工具”或“綠色版安裝包”。另外如果你當(dāng)前使用的模型端點(diǎn)和 Community 實(shí)驗(yàn)配置和官方模型名不對(duì)應(yīng)后續(xù)也會(huì)出現(xiàn)模型識(shí)別問(wèn)題這一點(diǎn)在第 7 節(jié)的排查表里會(huì)專(zhuān)門(mén)說(shuō)明。4. Skill 的核心機(jī)制與目錄規(guī)范安裝好 Claude Code 之后下一步就是理解 Skill 的存放位置和文件規(guī)范。4.1 項(xiàng)目級(jí) Skill 目錄最常用的是項(xiàng)目級(jí) Skill。在項(xiàng)目根目錄下創(chuàng)建一個(gè).claude/skills目錄里面每個(gè)子目錄就是一個(gè) Skill。結(jié)構(gòu)如下你的項(xiàng)目/ └── .claude/ ├── CLAUDE.md ├── settings.json └── skills/ ├── code-review/ │ └── SKILL.md ├── test-writer/ │ └── SKILL.md └── commit-helper/ └── SKILL.md.claude/CLAUDE.md項(xiàng)目級(jí)記憶文件。用來(lái)寫(xiě)團(tuán)隊(duì)的長(zhǎng)期約定比如“本項(xiàng)目使用 TypeScript”“提交信息必須符合 Conventional Commits”。Claude 每次任務(wù)都會(huì)參考它。.claude/settings.json工具權(quán)限控制文件?？梢韵拗?Claude 能執(zhí)行的命令范圍屬于安全邊界的一部分。.claude/skills/skill-name/SKILL.md每個(gè) Skill 的核心內(nèi)容。4.2 SKILL.md 的文件格式SKILL.md 分為兩部分開(kāi)頭的 YAML frontmatter以及正文的 Markdown 指令。--- name: skill-name description: 在什么時(shí)候、什么場(chǎng)景下使用這個(gè) Skill --- 這里是具體的執(zhí)行步驟和規(guī)則。frontmatter 里兩個(gè)字段最關(guān)鍵nameSkill 的名字一般用小寫(xiě)字母加連字符。這個(gè)名字會(huì)用于調(diào)用和日志展示。descriptionClaude 判斷“什么時(shí)候該用這個(gè) Skill”的依據(jù)。這句話(huà)寫(xiě)得越具體Skill 被正確觸發(fā)的概率越高。4.3 description 怎么寫(xiě)才不會(huì)被“無(wú)視”很多人寫(xiě)完 Skill 后發(fā)現(xiàn) Claude 壓根不調(diào)用問(wèn)題幾乎都出在 description 上。description 需要滿(mǎn)足三個(gè)條件以動(dòng)詞開(kāi)頭明確指出觸發(fā)動(dòng)作比如“當(dāng)需要審查代碼時(shí)使用”“當(dāng)需要生成單元測(cè)試時(shí)使用”。寫(xiě)清楚適用對(duì)象比如“針對(duì) Python 函數(shù)”“針對(duì)當(dāng)前 Pull Request 的改動(dòng)”。不要寫(xiě)成模糊的“幫我做事”而要寫(xiě)成“遇到這類(lèi)需求時(shí)讀取并遵循此 Skill 的規(guī)則”。下面是一個(gè)反例和一個(gè)正例反例description: 代碼審查技能用于提升代碼質(zhì)量。正例description: 當(dāng)用戶(hù)要求審查代碼、檢查 PR、或評(píng)估代碼質(zhì)量和安全隱患時(shí)使用。按安全、性能、可讀性、測(cè)試覆蓋四個(gè)維度輸出結(jié)論。區(qū)別很明顯反例像一句口號(hào)Claude 無(wú)法判斷什么時(shí)候觸發(fā)正例給出了明確的觸發(fā)條件和輸出方式。4.4 項(xiàng)目級(jí)與用戶(hù)級(jí) Skill項(xiàng)目級(jí) Skill 放在倉(cāng)庫(kù)目錄下最適合團(tuán)隊(duì)共享。因?yàn)橐坏┨峤坏?Git所有克隆倉(cāng)庫(kù)的成員都會(huì)拿到這套規(guī)范新人入職看到.claude目錄就能立刻了解團(tuán)隊(duì)對(duì) AI 的使用約定。如果你有自己固定的一套通用 Skill不想每個(gè)項(xiàng)目重復(fù)粘貼也可以放在用戶(hù)級(jí)目錄下。具體路徑在不同版本中可能不同建議安裝后查看官方文檔。更穩(wěn)妥的判斷是通用能力放用戶(hù)級(jí)項(xiàng)目相關(guān)規(guī)范放項(xiàng)目級(jí)。例如“提交信息規(guī)范”通常適合放項(xiàng)目級(jí)因?yàn)槊總€(gè)團(tuán)隊(duì)的提交規(guī)范不一定相同而“通用代碼審查模板”這種不依賴(lài)具體語(yǔ)言的可以放用戶(hù)級(jí)。5. 三個(gè)實(shí)用 Skill 組合實(shí)戰(zhàn)這一節(jié)是全文的重頭。我們直接用命令創(chuàng)建一個(gè)可用的 Skill 組合然后逐個(gè)解釋 SKILL.md 的內(nèi)容。5.1 創(chuàng)建目錄骨架在項(xiàng)目根目錄下執(zhí)行mkdir -p .claude/skills/code-review mkdir -p .claude/skills/test-writer mkdir -p .claude/skills/commit-helper如果是在 Windows 上使用 CMD可以用mkdir .claude\skills\code-review mkdir .claude\skills\test-writer mkdir .claude\skills\commit-helper創(chuàng)建完成后目錄結(jié)構(gòu)應(yīng)該和 4.1 節(jié)展示的一致。5.2 Skill 1code-review把代碼審查變成標(biāo)準(zhǔn)動(dòng)作先創(chuàng)建.claude/skills/code-review/SKILL.md內(nèi)容如下--- name: code-review description: 當(dāng)用戶(hù)要求審查代碼、檢查代碼質(zhì)量、評(píng)估 PR 或查看某個(gè)文件的安全風(fēng)險(xiǎn)時(shí)使用。按安全、性能、可讀性、測(cè)試覆蓋四個(gè)維度輸出結(jié)論。 --- # Code Review Skill 請(qǐng)按以下流程審查代碼 1. 先讀取目標(biāo)文件分析代碼改動(dòng)范圍。 2. 按四個(gè)維度輸出結(jié)論 - 安全性注入風(fēng)險(xiǎn)、權(quán)限校驗(yàn)、敏感信息泄露、依賴(lài)安全問(wèn)題。 - 性能不必要的循環(huán)、重復(fù)請(qǐng)求、內(nèi)存使用、IO 開(kāi)銷(xiāo)。 - 可讀性與維護(hù)性命名、函數(shù)長(zhǎng)度、重復(fù)代碼、模塊劃分。 - 測(cè)試覆蓋是否有對(duì)應(yīng)測(cè)試、邊界條件是否覆蓋、異常路徑是否處理。 3. 每個(gè)問(wèn)題標(biāo)注嚴(yán)重級(jí)別嚴(yán)重必須改/ 建議應(yīng)該改/ 提醒可選優(yōu)化。 4. 不要輸出空泛評(píng)價(jià)所有意見(jiàn)必須能落到具體代碼位置。 輸出模板 ## 審查結(jié)論 整體質(zhì)量?jī)?yōu) / 良 / 需改進(jìn) ### 嚴(yán)重問(wèn)題 ### 建議問(wèn)題 ### 可選優(yōu)化這個(gè) Skill 的價(jià)值在于它把“代碼審查”從一個(gè)模糊的對(duì)話(huà)請(qǐng)求變成了一套固定輸出格式。你不需要每次告訴 Claude“你要從哪幾個(gè)維度看”它自己會(huì)按模板來(lái)。5.3 Skill 2test-writer把測(cè)試生成變成流程第二個(gè) Skill 用于生成單元測(cè)試。創(chuàng)建.claude/skills/test-writer/SKILL.md--- name: test-writer description: 當(dāng)用戶(hù)要求為某個(gè)函數(shù)、類(lèi)或接口補(bǔ)充單元測(cè)試時(shí)使用。支持 Python、TypeScript、Java 等主流語(yǔ)言自動(dòng)匹配項(xiàng)目使用的測(cè)試框架。 --- # Test Writer Skill 1. 先分析目標(biāo)模塊的輸入、輸出和邊界條件。 2. 根據(jù)項(xiàng)目語(yǔ)言選擇測(cè)試框架 - Pythonpytest - TypeScript / JavaScriptVitest 或 Jest - JavaJUnit 5 3. 輸出測(cè)試文件路徑和完整測(cè)試代碼。 4. 測(cè)試用例必須覆蓋 - 正常輸入路徑。 - 空值、越界、非法參數(shù)等邊界情況。 - 預(yù)期拋出異常的異常路徑。 5. 如果項(xiàng)目已有測(cè)試風(fēng)格優(yōu)先保持風(fēng)格一致。 6. 生成結(jié)束后給出當(dāng)前項(xiàng)目運(yùn)行測(cè)試的命令。這里有一個(gè)容易踩的坑Claude 默認(rèn)生成測(cè)試代碼時(shí)可能不會(huì)先檢查項(xiàng)目已有的測(cè)試風(fēng)格。如果你在description里不強(qiáng)調(diào)“保持項(xiàng)目風(fēng)格一致”它有時(shí)會(huì)生成一個(gè)寫(xiě)法完全不同的測(cè)試文件雖然能跑但會(huì)讓維護(hù)者很頭疼。加入第 5 條之后Claude 會(huì)先看項(xiàng)目里已有的測(cè)試文件再動(dòng)手。5.4 Skill 3commit-helper把 Git 提交信息變成規(guī)范第三個(gè) Skill 負(fù)責(zé) Git 提交信息。創(chuàng)建.claude/skills/commit-helper/SKILL.md--- name: commit-helper description: 當(dāng)用戶(hù)準(zhǔn)備提交代碼、需要編寫(xiě) git commit message、或整理 CHANGELOG 時(shí)使用。將根據(jù)項(xiàng)目改動(dòng)生成規(guī)范提交信息。 --- # Commit Helper Skill 1. 使用 git status 和 git diff --stat 查看本次改動(dòng)文件。 2. 閱讀有代表性的 diff理解改動(dòng)意圖。 3. 按照 Conventional Commits 規(guī)范生成提交信息 type(scope): subject type 取值范圍 - feat新功能 - fix修復(fù)問(wèn)題 - docs文檔變更 - style格式調(diào)整 - refactor重構(gòu) - perf性能優(yōu)化 - test測(cè)試相關(guān) - chore構(gòu)建、依賴(lài)等雜項(xiàng) 4. 將提交信息展示給用戶(hù)獲得確認(rèn)后再建議執(zhí)行 git commit。 5. 不要擅自提交代碼除非用戶(hù)明確授權(quán)。很多人會(huì)覺(jué)得提交信息一個(gè)git commit -m fix bug就夠了沒(méi)必要交給 AI。但實(shí)際上在多分支協(xié)作或需要生成 CHANGELOG 的項(xiàng)目里提交信息的規(guī)范性直接影響后續(xù)的自動(dòng)化發(fā)布和版本追溯。如果團(tuán)隊(duì)準(zhǔn)備接語(yǔ)義化版本發(fā)布流程這一條 Skill 的價(jià)值會(huì)立刻體現(xiàn)。5.5 用 CLAUDE.md 把三個(gè) Skill 串起來(lái)三個(gè) Skill 單獨(dú)用都有效但組合起來(lái)才更像“一條流水線(xiàn)”。這個(gè)組合的關(guān)鍵是在.claude/CLAUDE.md里定義固定順序// .claude/CLAUDE.md 團(tuán)隊(duì)開(kāi)發(fā)約定 1. 修改代碼后先運(yùn)行 test-writer 生成或補(bǔ)充單元測(cè)試。 2. 提交代碼前使用 code-review 完成一次審查。 3. 最終提交時(shí)使用 commit-helper 生成規(guī)范提交信息。 4. 涉及破壞性變更時(shí)必須同時(shí)給出回滾方案。CLAUDE.md 的作用是“長(zhǎng)期記憶”。Claude 在每次執(zhí)行任務(wù)時(shí)都會(huì)參考它所以它會(huì)知道“這個(gè)團(tuán)隊(duì)要求先補(bǔ)測(cè)試、再審查、最后規(guī)范提交”。三個(gè) Skill 就不再是孤立的提示詞而是被統(tǒng)一到一個(gè)工作流里。5.6 交互式調(diào)用示例啟動(dòng) Claude Codeclaude在交互界面中輸入code-review 審查 src/main.py或者一次性做多步請(qǐng)為 utils/date.py 生成單元測(cè)試然后審查一下測(cè)試代碼。如果你希望跳過(guò)交互直接以非交互方式執(zhí)行可以用claude -p test-writer 為 utils/date.py 生成 pytest 用例這種非交互方式適合在腳本中調(diào)用后面驗(yàn)證時(shí)會(huì)用到。6. 運(yùn)行效果與驗(yàn)證方法Skill 配好后怎么判斷它是真的生效而不是假裝生效這一節(jié)給出可執(zhí)行的驗(yàn)證步驟。6.1 驗(yàn)證 Skill 目錄被識(shí)別在 Claude Code 交互界面中輸入斜杠命令查看當(dāng)前會(huì)話(huà)可用的技能列表。/help或者直接輸入 Skill 名看是否有補(bǔ)全提示code-review如果輸入后能看到code-review、test-writer、commit-helper三個(gè)選項(xiàng)說(shuō)明 Skill 已經(jīng)被加載。6.2 用一個(gè)最小函數(shù)驗(yàn)證 code-review先創(chuàng)建一個(gè)測(cè)試文件# 文件路徑src/example.py def get_user_name(user_id, db): sql SELECT name FROM users WHERE id user_id return db.execute(sql)然后在 Claude Code 中調(diào)用code-review 審查 src/example.py預(yù)期輸出中應(yīng)該包含四個(gè)維度安全性SQL 注入風(fēng)險(xiǎn)、性能無(wú)大問(wèn)題但建議使用參數(shù)化查詢(xún)、可讀性函數(shù)命名沒(méi)問(wèn)題但缺少類(lèi)型注解、測(cè)試覆蓋缺少測(cè)試。如果輸出只是“代碼寫(xiě)得不錯(cuò)”這類(lèi)評(píng)價(jià)說(shuō)明 Skill 的正文沒(méi)有被正確讀取需要檢查 frontmatter。6.3 驗(yàn)證 test-writer繼續(xù)用上面這個(gè)例子claude -p test-writer 為 src/example.py 生成 pytest 測(cè)試預(yù)期輸出會(huì)包含一個(gè)test_example.py的代碼塊并且至少覆蓋正常路徑和異常路徑。你可以把生成的代碼保存下來(lái)用 pytest 手動(dòng)運(yùn)行確認(rèn)。6.4 驗(yàn)證 commit-helper在項(xiàng)目工作區(qū)做一次改動(dòng)后調(diào)用commit-helper 幫我生成提交信息預(yù)期輸出是一行類(lèi)似下面的信息fix(users): 使用參數(shù)化查詢(xún)修復(fù)用戶(hù)查詢(xún)的 SQL 注入風(fēng)險(xiǎn)如果沒(méi)有生成這種格式而是給了一堆廢話(huà)說(shuō)明 SKILL.md 中的模板沒(méi)有被遵循或者當(dāng)前版本對(duì) Markdown 指令的理解方式和你預(yù)期不同可以適當(dāng)把步驟寫(xiě)得更短、更指令化。6.5 失敗時(shí)的第一排查順序如果運(yùn)行結(jié)果不符合預(yù)期不要急著改內(nèi)容先按順序查目錄名和文件名是否完全正確必須是.claude/skills/skill-name/SKILL.md。frontmatter 是否使用了---包裹。description是否準(zhǔn)確描述了當(dāng)前任務(wù)場(chǎng)景。是否調(diào)用了正確的 Skill 名。當(dāng)前 Claude Code 版本是否過(guò)舊舊版本可能不支持新加的 Skill 功能。7. 常見(jiàn)問(wèn)題與排查思路下面把實(shí)際使用中最高頻的問(wèn)題整理成一張排查表。問(wèn)題現(xiàn)象可能原因排查方式解決方案claude: command not foundnpm 全局 bin 目錄不在 PATH 中執(zhí)行npm prefix -g查看全局目錄將該目錄加入系統(tǒng) PATH重開(kāi)終端Skill 明明寫(xiě)了卻不生效目錄位置寫(xiě)錯(cuò)或 SKILL.md 文件名錯(cuò)誤檢查是否在.claude/skills/name/SKILL.md按規(guī)范重建文件注意大小寫(xiě)輸入skill-name沒(méi)反應(yīng)frontmatter 缺失或解析失敗用編輯器檢查文件頭部是否被 BOM 干擾刪除 BOM確認(rèn)name字段正確Claude 不主動(dòng)調(diào)用 Skilldescription 寫(xiě)得像口號(hào)無(wú)法觸發(fā)重讀 description 是否包含觸發(fā)場(chǎng)景改成“當(dāng)用戶(hù)要求……時(shí)使用”句式生成內(nèi)容總是不符合團(tuán)隊(duì)風(fēng)格缺少項(xiàng)目級(jí)約定查看.claude/CLAUDE.md是否為空在 CLAUDE.md 中補(bǔ)充團(tuán)隊(duì)規(guī)范提示xxx is not a model this version of claude code recognizes使用了當(dāng)前版本無(wú)法識(shí)別的模型名或?qū)嶒?yàn)性配置檢查當(dāng)前claude --version版本確認(rèn)模型名恢復(fù)官方默認(rèn)模型或升級(jí) Claude Code 后再試下載安裝時(shí)進(jìn)度卡住網(wǎng)絡(luò)環(huán)境受限觀察 npm 日志和下載地址切換 npm 鏡像源重試安裝工具執(zhí)行被拒絕當(dāng)前權(quán)限配置限制了命令查看settings.json中的權(quán)限設(shè)置按最小權(quán)限原則放開(kāi)明確需要的命令生產(chǎn)環(huán)境需人工審批這里的模型名報(bào)錯(cuò)需要特別說(shuō)明這個(gè)問(wèn)題通常出現(xiàn)在用戶(hù)手動(dòng)配置了第三方模型端點(diǎn)或?qū)嶒?yàn)性模型名之后。AI 編程工具對(duì)模型名的識(shí)別和當(dāng)前版本強(qiáng)相關(guān)在沒(méi)有官方文檔明確支持的情況下不建議在生產(chǎn)環(huán)境使用未經(jīng)驗(yàn)證的模型名。穩(wěn)妥的做法是保持 Claude Code 默認(rèn)模型配置。8. 最佳實(shí)踐與工程建議Skill 寫(xiě)得好不好不是看代碼多少而是看“觸達(dá)率”和“穩(wěn)定性”。觸達(dá)率是指任務(wù)出現(xiàn)時(shí) Skill 能被正確調(diào)用的概率穩(wěn)定性是指無(wú)論 Claude 怎么理解輸出結(jié)果都能保持近似格式。下面這組建議能同時(shí)提升兩者。8.1 Skill 設(shè)計(jì)原則一個(gè) Skill 只做一件事不要把“代碼審查、寫(xiě)文檔、生成測(cè)試、處理 Git”全部塞進(jìn)一個(gè) SKILL.md。一個(gè) Skill 只負(fù)責(zé)一個(gè)職責(zé)原因有兩點(diǎn)description 更容易寫(xiě)清楚Claude 調(diào)用時(shí)會(huì)更快匹配。正文更短模型不會(huì)“讀了后半段忘了前半段”。如果發(fā)現(xiàn)一個(gè) SKILL.md 里出現(xiàn)了兩套不相關(guān)的步驟就應(yīng)該拆成兩個(gè) Skill。8.2 description 的統(tǒng)一句式推薦在這種格式中填充description: 當(dāng)用戶(hù)要求{動(dòng)作}時(shí)使用。適用于{場(chǎng)景}。輸出應(yīng)按{格式}完成。例如description: 當(dāng)用戶(hù)要求編寫(xiě)提交信息時(shí)使用。適用于正在準(zhǔn)備 git commit 的開(kāi)發(fā)者。輸出應(yīng)符合 Conventional Commits 規(guī)范。這個(gè)句式把“觸發(fā)條件、適用對(duì)象、輸出要求”三個(gè)關(guān)鍵信息都覆蓋了。8.3 把 Skill 納入版本管理.claude/skills目錄建議提交到 Git 倉(cāng)庫(kù)。這樣團(tuán)隊(duì)每個(gè)成員 Clone 后都會(huì)自動(dòng)獲得同一套技能配置不會(huì)出現(xiàn)“我本地可以、你本地不行”的情況。建議在倉(cāng)庫(kù)的 README 中加一節(jié)說(shuō)明## AI 輔助開(kāi)發(fā) 本倉(cāng)庫(kù)使用 Claude Code 作為 AI 編程輔助工具。 - 代碼審查code-review - 單元測(cè)試test-writer - 提交信息commit-helper8.4 安全邊界讓 AI 動(dòng)代碼前先確認(rèn)Skill 賦予了 Claude 執(zhí)行任務(wù)的能力但能力越強(qiáng)越需要邊界。建議從三個(gè)層面控制權(quán)限層通過(guò).claude/settings.json控制哪些命令允許自動(dòng)執(zhí)行哪些必須詢(xún)問(wèn)用戶(hù)。內(nèi)容層不要在 SKILL.md 中寫(xiě)入任何密鑰、內(nèi)部域名、敏感路徑和涉密信息因?yàn)樗琼?xiàng)目文件會(huì)被提交到倉(cāng)庫(kù)并共享。操作層涉及刪除文件、修改數(shù)據(jù)庫(kù)結(jié)構(gòu)、發(fā)布產(chǎn)物等危險(xiǎn)操作時(shí)讓 AI 先輸出執(zhí)行計(jì)劃等待人工確認(rèn)后再執(zhí)行。8.5 模型接入穩(wěn)定優(yōu)先平時(shí)關(guān)注 AI 編程工具的同學(xué)可能會(huì)看到社區(qū)里有人把 Claude Code 接到其他模型上實(shí)驗(yàn)。這類(lèi)玩法適合學(xué)習(xí)和研究但不建議直接引入生產(chǎn)環(huán)境。最直接的原因就是兼容性不同模型對(duì)工具調(diào)用的格式、上下文長(zhǎng)度、指令遵循程度的差異很大某個(gè)版本能用升級(jí)后可能就報(bào)“model not recognized”之類(lèi)的錯(cuò)誤。如果你真的想嘗試唯一正確的做法是在獨(dú)立環(huán)境里做實(shí)驗(yàn)使用官方文檔明確支持的模型名并且保證切換失敗時(shí)可以快速回滾默認(rèn)配置。生產(chǎn)環(huán)境保持原廠(chǎng)配置這是最穩(wěn)的選擇。8.6 Skill 的維護(hù)節(jié)奏Skill 不是寫(xiě)一次就一勞永逸的。建議在以下時(shí)刻主動(dòng)更新團(tuán)隊(duì)規(guī)范發(fā)生變化時(shí)。Claude Code 大版本升級(jí)后用現(xiàn)有 Skill 跑一遍舊任務(wù)確認(rèn)輸出沒(méi)有明顯退化。發(fā)現(xiàn) Skill 生成的輸出總是需要人工二次修改時(shí)應(yīng)該修改 Skill 正文補(bǔ)充約束而不是每次手動(dòng)糾正。9. 總結(jié)與下一步實(shí)踐這篇文章的核心脈絡(luò)可以濃縮成三句話(huà)第一Claude Code 的價(jià)值不在對(duì)話(huà)而在 Agent 能力Skill 是給它注入能力的標(biāo)準(zhǔn)方式。第二一個(gè) Skill 就是一個(gè)SKILL.md文件關(guān)鍵是寫(xiě)清楚description觸發(fā)時(shí)機(jī)和正文的執(zhí)行步驟目錄規(guī)范是.claude/skills/skill-name/SKILL.md。第三三個(gè)實(shí)用 Skill 可以組合成一條連貫的開(kāi)發(fā)流程test-writer補(bǔ)測(cè)試、code-review做審查、commit-helper保證提交規(guī)范。組合起來(lái)之后它就不再是三個(gè)孤立的提示詞而是一套可復(fù)用的團(tuán)隊(duì)工程規(guī)范。如果你剛接觸這塊建議現(xiàn)在動(dòng)手做一件最小的事在任意一個(gè)最常用的 Git 項(xiàng)目里創(chuàng)建.claude/skills/commit-helper/SKILL.md把第 5.4 節(jié)的代碼復(fù)制進(jìn)去然后下次提交代碼時(shí)試著調(diào)用一次。跑通這一個(gè)再逐步加上測(cè)試生成和代碼審查。不要一次性把十幾個(gè) Skill 全部堆進(jìn)倉(cāng)庫(kù)Skill 越多維護(hù)成本越高先用最小集跑通日常流程再按實(shí)際需要擴(kuò)充。另外給一個(gè)新入門(mén)的團(tuán)隊(duì)一個(gè)建議Skill 的引入最好和團(tuán)隊(duì)現(xiàn)有流程綁定而不是另起爐灶。比如你們已經(jīng)在用 Conventional Commits那就把 commit-helper 直接對(duì)應(yīng)到現(xiàn)有規(guī)范你們已經(jīng)有一套代碼評(píng)審檢查單那就把 code-review 的內(nèi)容改成團(tuán)隊(duì)自己的版本。這樣 AI 不是替代原有流程而是在原流程里多了一個(gè)穩(wěn)定的執(zhí)行者。過(guò)一個(gè)月回頭看你會(huì)發(fā)現(xiàn)真正有價(jià)值的不是某個(gè) Skill 的寫(xiě)法而是這套“把團(tuán)隊(duì)規(guī)范固化成 AI 可執(zhí)行指令”的思維方式。