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