1. 從 50 個 Skill 里爬出來的血淚賬先交代背景。過去大半年我陸陸續(xù)續(xù)寫了 50 個 Claude Code Skill覆蓋代碼生成、接口文檔、數(shù)據庫遷移、前端組件、測試用例、部署腳本這些日常活兒。寫到最后我回頭一盤點發(fā)現(xiàn)前 30 個基本等于白寫——不是不能用而是用起來別扭、維護成本高、復用率低最后大部分都被我自己棄用了。這篇文章就是把這 50 個 Skill 的踩坑過程攤開講。核心關鍵詞是Claude Code、Skill、SKILL.md、MCP順帶會聊到Spring Boot場景下的落地案例。適合誰看三類人一是剛開始接觸 Claude Code Skill、還在糾結怎么寫第一個 SKILL.md 的人二是已經寫了一堆 Skill 但發(fā)現(xiàn)復用率上不去、維護越來越累的人三是想把 Skill 和 MCP 結合起來做工程化落地的人。不管你是剛上手還是已經踩過幾腳泥這篇應該都能幫你少走點彎路。我先把結論擺前面省得你看到一半才反應過來Skill 的價值不在于能跑而在于穩(wěn)定復用。前 30 個 Skill 之所以白寫根本原因是我把它們當成了一次性腳本來寫而不是當成可維護的工程資產來設計。這個認知轉變是我寫完第 31 個 Skill 之后才真正想明白的。下面我按四個部分展開先講整體設計思路的轉變再拆核心細節(jié)和實操要點然后是完整的實操流程最后是我整理的常見問題排查表。每一部分都是真金白銀換來的不是從文檔里抄的。2. 整體設計思路為什么前 30 個 Skill 會白寫2.1 把 Skill 當腳本寫是最大的坑我最早寫 Skill 的思路特別樸素有個重復性任務就寫個 Skill 把它固化下來。比如生成 Spring Boot Controller 模板、把 MyBatis 的 XML 轉成注解、根據實體類生成建表 SQL。每個 Skill 單獨看都能用但問題在于——它們之間沒有共享上下文沒有統(tǒng)一的輸入輸出約定沒有版本管理。結果就是寫第 5 個 Skill 的時候我復制了第 3 個的 SKILL.md 結構寫第 12 個的時候又復制了第 8 個的。到第 20 個的時候我發(fā)現(xiàn)有 6 個 Skill 的 prompt 里都重復寫了同一段項目使用 Spring Boot 3.x MyBatis-Plus包名統(tǒng)一為 com.xxx的上下文。這段上下文一旦要改比如項目升級到 Spring Boot 3.2我得挨個改 6 個文件。這就是典型的腳本思維每個 Skill 自包含不考慮復用和抽象。而正確的做法應該是工程思維把公共上下文抽出來把輸入輸出標準化把 Skill 當成有生命周期的資產來管理。2.2 SKILL.md 的結構決定了 Skill 的上限很多人寫 SKILL.md 就是隨手寫一段 prompt前面加個標題就完事了。我前 30 個 Skill 基本都是這個路子。后來我才意識到SKILL.md 的結構直接決定了這個 Skill 能不能被穩(wěn)定觸發(fā)、能不能被復用、能不能被維護。一個合格的 SKILL.md 至少應該包含這幾塊觸發(fā)條件什么時候用這個 Skill、輸入約定用戶需要提供什么、執(zhí)行步驟Skill 內部怎么處理、輸出格式產出什么、邊界說明什么情況下不該用。我前 30 個 Skill 里有超過一半只寫了執(zhí)行步驟觸發(fā)條件和邊界說明基本空白。結果就是 Claude Code 經常在不該觸發(fā)的時候觸發(fā)或者觸發(fā)了但輸入不完整導致輸出亂七八糟。2.3 為什么是 30 這個數(shù)字你可能會問為什么偏偏是前 30 個白寫不是前 20 或前 40說實話這個數(shù)字不是精確的是我復盤時的一個大致分界。前 30 個 Skill 我基本是想到就寫沒有統(tǒng)一規(guī)劃從第 31 個開始我做了三件事建立公共上下文庫、統(tǒng)一 SKILL.md 模板、引入 MCP 做外部能力補充。這三件事做完之后后面 20 個 Skill 的復用率和穩(wěn)定性明顯上了一個臺階。所以30更像是一個認知拐點的標記而不是一個精確的統(tǒng)計數(shù)字。如果你現(xiàn)在正處在想到就寫的階段那這篇文章就是寫給你的。2.4 Skill 和 MCP 的分工要提前想清楚這是我在第 35 個 Skill 左右才想明白的事。Skill 負責流程編排和上下文注入MCP 負責外部能力調用。兩者分工不清就會導致 Skill 里塞了一堆本該由 MCP 做的事或者 MCP 配置了一堆本該由 Skill 處理的邏輯。舉個 Spring Boot 場景的例子我要做一個根據需求描述生成完整 CRUD 模塊的 Skill。這個 Skill 需要讀項目現(xiàn)有的實體類、需要查數(shù)據庫表結構、需要寫文件。讀實體類和寫文件是本地能力Skill 自己就能做但查數(shù)據庫表結構這件事如果項目用的是遠程數(shù)據庫就需要通過 MCP 去調用數(shù)據庫工具。如果我把查數(shù)據庫這件事也硬塞進 Skill 的 prompt 里那這個 Skill 就綁死了特定的數(shù)據庫環(huán)境換個項目就廢了。正確的做法是Skill 負責什么時候查、查什么、拿到結果怎么用MCP 負責實際去查。這樣 Skill 是可移植的MCP 是可替換的。3. 核心細節(jié)解析SKILL.md 到底該怎么寫3.1 觸發(fā)條件要寫得像路由規(guī)則觸發(fā)條件是 SKILL.md 里最容易被忽視、但最重要的一塊。我前 30 個 Skill 里觸發(fā)條件基本就是一句話當用戶需要生成 Controller 時使用。這種寫法太模糊了Claude Code 根本判斷不準。好的觸發(fā)條件應該像路由規(guī)則一樣精確。比如## 觸發(fā)條件 當滿足以下全部條件時觸發(fā) 1. 用戶明確提到生成 Controller、創(chuàng)建接口、新增 REST 接口之一 2. 當前工作目錄下存在 pom.xml 或 build.gradle 3. 用戶提供了實體類名或表名 不滿足任一條件時先向用戶確認不要直接執(zhí)行。這樣寫的好處是Claude Code 在判斷是否觸發(fā)時有明確的依據不會因為用戶隨口提了一句接口就貿然觸發(fā)。我實測下來加了精確觸發(fā)條件之后誤觸發(fā)率從大概三成降到了不到一成。3.2 輸入約定要明確缺什么就問輸入約定這塊我踩過的坑是Skill 假設用戶會提供完整信息但實際用戶往往只給一半。比如我寫過一個根據表名生成 MyBatis Mapper的 Skill假設用戶會提供表名和字段列表。結果用戶經常只給表名Skill 就開始瞎編字段生成的 Mapper 完全不能用。后來我改成這樣## 輸入約定 必需輸入 - 表名必填 - 字段列表必填格式字段名 類型 注釋 可選輸入 - 包名默認 com.example.mapper - 是否生成 XML默認否 如果用戶未提供必需輸入逐項詢問不要自行假設。關鍵就是那句不要自行假設。Claude Code 很聰明聰明到會幫你腦補缺失信息但腦補出來的東西往往不對。明確告訴它缺什么就問比讓它自由發(fā)揮靠譜得多。3.3 執(zhí)行步驟要拆到可驗證的粒度執(zhí)行步驟是 SKILL.md 的主體也是最容易寫得太粗或太細的地方。寫太粗Claude Code 不知道具體怎么做寫太細又變成了死板的腳本失去靈活性。我的經驗是拆到每一步都有明確產出、且產出可驗證的粒度。比如生成 CRUD 模塊這個 Skill我拆成這幾步讀取實體類提取字段列表產出字段清單可驗證字段數(shù)和實體類一致根據字段清單生成建表 SQL產出SQL 文件可驗證能執(zhí)行不報錯生成 Mapper 接口產出Java 文件可驗證編譯通過生成 Service 層產出Java 文件可驗證編譯通過生成 Controller 層產出Java 文件可驗證編譯通過每一步都有產出每一步都能驗證。這樣即使中間某一步出錯也能快速定位是哪一步的問題而不是面對一個整體跑不通的黑盒。3.4 輸出格式要固定方便下游消費輸出格式這塊我前 30 個 Skill 基本沒管導致每個 Skill 的輸出風格都不一樣。有的輸出 Markdown有的輸出純文本有的直接輸出代碼塊。結果就是這些 Skill 之間沒法串聯(lián)——A Skill 的輸出沒法直接喂給 B Skill。后來我統(tǒng)一了輸出格式所有 Skill 的輸出都遵循摘要 詳情 下一步建議三段式。摘要用一兩句話說明做了什么詳情用代碼塊或表格展示具體產出下一步建議告訴用戶接下來可以做什么。這樣不僅人看著舒服Skill 之間也能互相消費輸出。3.5 邊界說明是防呆設計邊界說明是我最后才補上的一塊但補上之后效果立竿見影。所謂邊界說明就是明確告訴 Claude Code什么情況下不該用這個 Skill。比如生成 CRUD 模塊這個 Skill邊界說明寫的是## 邊界說明 以下情況不要使用本 Skill - 項目不是 Spring Boot 項目 - 實體類使用了 JPA 注解而非 MyBatis-Plus 注解 - 用戶要求生成的是 GraphQL 接口而非 REST 接口 遇到以上情況向用戶說明原因并建議替代方案。這段說明的價值在于它防止了 Skill 在不適用的場景下被強行觸發(fā)避免了用錯工具導致的返工。我實測下來加了邊界說明之后因為Skill 用錯場景導致的返工減少了大概一半。4. 實操過程從零搭一個可復用的 Skill 體系4.1 第一步建立公共上下文庫這是我從第 31 個 Skill 開始做的第一件事。具體做法是在項目根目錄建一個.claude/context/目錄里面放幾個公共上下文文件比如project.md項目技術棧、包名約定、代碼風格、database.md數(shù)據庫連接信息、表命名規(guī)范、api.md接口規(guī)范、返回格式約定。然后在每個 SKILL.md 里通過引用這些文件來注入上下文而不是把上下文硬編碼在 Skill 里。比如## 上下文 執(zhí)行前先讀取 .claude/context/project.md 和 .claude/context/api.md 按照其中的約定執(zhí)行。如果文件不存在向用戶確認項目約定。這樣做的好處是項目約定變了只需要改一處所有 Skill 自動生效。我實測下來項目從 Spring Boot 2.7 升級到 3.2 的時候只改了project.md一個文件所有 Skill 就都適配了省了大量重復勞動。4.2 第二步統(tǒng)一 SKILL.md 模板第二件事是統(tǒng)一模板。我定了一個標準模板所有新 Skill 都按這個模板寫# Skill 名稱 ## 觸發(fā)條件 精確的路由規(guī)則 ## 輸入約定 必需輸入 可選輸入 缺失處理 ## 上下文 需要讀取的公共上下文文件 ## 執(zhí)行步驟 拆到可驗證粒度 ## 輸出格式 摘要 詳情 下一步建議 ## 邊界說明 什么情況下不該用這個模板看起來簡單但它強制我在寫每個 Skill 的時候都思考這七個問題。前 30 個 Skill 之所以白寫很大程度上就是因為沒有這個模板寫的時候想到哪寫到哪漏掉了很多關鍵信息。4.3 第三步引入 MCP 做能力補充第三件事是引入 MCP。MCP 的全稱是 Model Context Protocol簡單說就是一套讓 AI 調用外部工具的協(xié)議。在 Claude Code 里MCP 可以讓 Skill 具備訪問外部系統(tǒng)的能力比如查數(shù)據庫、調 API、讀遠程文件。我在 Spring Boot 項目里最常用的 MCP 配置是數(shù)據庫查詢。配置好之后Skill 就可以通過 MCP 去查真實的表結構而不是靠用戶描述或者靠猜。具體配置大概長這樣以常見的數(shù)據庫 MCP 為例{ mcpServers: { database: { command: npx, args: [-y, modelcontextprotocol/server-postgres], env: { DATABASE_URL: postgresql://user:passlocalhost:5432/mydb } } } }配置好之后Skill 里就可以這樣用## 執(zhí)行步驟 1. 通過 MCP 的 database 工具查詢目標表結構 2. 根據表結構生成實體類 3. 根據實體類生成 Mapper、Service、Controller這里的關鍵是Skill 只負責調用 MCP不負責實現(xiàn) MCP。這樣 Skill 是可移植的換個數(shù)據庫只需要換 MCP 配置Skill 本身不用改。4.4 第四步建立 Skill 版本管理第四件事是版本管理。我前 30 個 Skill 基本沒有版本概念改了就直接覆蓋出了問題想回滾都回不去。后來我給每個 Skill 加了版本號放在 SKILL.md 的頭部--- name: generate-crud version: 1.2.0 last_updated: 2024-05-20 ---版本號遵循語義化版本規(guī)范大版本號變了說明有不兼容改動小版本號變了說明加了功能補丁號變了說明只是修了 bug。這樣我在用 Skill 的時候能一眼看出這個 Skill 是不是最新版改動大不大。4.5 第五步寫測試用例驗證 Skill第五件事是寫測試用例。這是我從第 40 個 Skill 開始才做的但做了之后發(fā)現(xiàn)太值了。具體做法是給每個 Skill 準備 2-3 個測試用例覆蓋正常場景、邊界場景、異常場景。比如生成 CRUD 模塊這個 Skill我準備了三個測試用例用例編號場景輸入預期輸出TC-01正常場景完整實體類 表名生成 4 個文件編譯通過TC-02邊界場景實體類只有 1 個字段生成 4 個文件編譯通過TC-03異常場景實體類不存在提示錯誤不生成文件每次改完 Skill我都跑一遍這三個用例確保沒有引入回歸問題。這個習慣幫我避免了好幾次改了一個地方壞了另一個地方的事故。4.6 第六步Skill 之間的串聯(lián)第六件事是讓 Skill 之間能串聯(lián)。單個 Skill 再強能力也有限但多個 Skill 串起來就能完成復雜任務。串聯(lián)的關鍵是統(tǒng)一輸出格式讓 A Skill 的輸出能直接作為 B Skill 的輸入。比如我有一個需求分析Skill輸出是結構化的需求清單還有一個代碼生成Skill輸入是需求清單。這兩個 Skill 串起來就能實現(xiàn)從需求描述到代碼生成的端到端流程。我實測下來這個串聯(lián)流程能把一個中等復雜度的 CRUD 模塊開發(fā)時間從半天壓縮到半小時左右。5. 常見問題與排查技巧實錄5.1 Skill 不觸發(fā)怎么辦這是最常見的問題。Skill 寫好了但 Claude Code 就是不觸發(fā)。排查思路按順序來第一檢查觸發(fā)條件是不是寫得太窄。比如你寫當用戶說生成 Controller時觸發(fā)但用戶實際說的是幫我寫個接口那就觸發(fā)不了。解決辦法是把觸發(fā)條件寫寬一點覆蓋同義詞。第二檢查 SKILL.md 的位置對不對。Claude Code 對 Skill 文件的位置有要求放錯地方就加載不到。一般是放在.claude/skills/目錄下每個 Skill 一個子目錄子目錄里放 SKILL.md。第三檢查文件編碼和格式。SKILL.md 必須是 UTF-8 編碼Markdown 格式要正確。我有一次因為文件里有個不可見字符導致整個 Skill 加載失敗排查了半天才發(fā)現(xiàn)。5.2 Skill 觸發(fā)了但輸出不對這個問題比不觸發(fā)更隱蔽。Skill 觸發(fā)了但輸出質量差、格式亂、內容不對。排查思路第一檢查輸入是不是完整。很多時候輸出不對是因為輸入不全Claude Code 自己腦補了。解決辦法是在 SKILL.md 里明確寫缺什么就問。第二檢查上下文是不是注入成功。如果 Skill 依賴公共上下文文件但文件沒讀到輸出就會跑偏?？梢栽?SKILL.md 里加一步確認上下文已讀取讀不到就報錯。第三檢查執(zhí)行步驟是不是太粗。步驟太粗Claude Code 就會自由發(fā)揮發(fā)揮出來的東西往往不符合預期。解決辦法是把步驟拆細每一步都有明確產出。5.3 Skill 之間沖突怎么辦當你寫的 Skill 多了難免會遇到兩個 Skill 都想觸發(fā)的情況。比如生成 Controller和生成 CRUD 模塊這兩個 Skill用戶說生成用戶模塊的接口時兩個都可能觸發(fā)。解決辦法是在觸發(fā)條件里加優(yōu)先級和互斥規(guī)則。比如## 觸發(fā)條件 優(yōu)先級高 互斥當 generate-crud 已觸發(fā)時本 Skill 不觸發(fā)或者在更上層的 Skill 里做路由根據用戶意圖分發(fā)給不同的子 Skill。我現(xiàn)在的做法是建一個總入口Skill所有請求先經過它由它判斷該走哪個子 Skill。5.4 MCP 調用失敗怎么排查MCP 調用失敗的原因比較多我整理了一個排查表現(xiàn)象可能原因排查方法MCP 工具列表為空MCP 服務沒啟動檢查 MCP 配置文件的 command 和 args調用超時網絡問題或服務響應慢檢查網絡連接看 MCP 服務日志返回權限錯誤認證信息不對檢查 MCP 配置里的 env 變量返回數(shù)據格式不對MCP 服務版本不匹配檢查 MCP 服務版本和協(xié)議版本我踩過最坑的一次是 MCP 配置文件里路徑寫錯了導致服務啟動失敗但 Claude Code 沒有任何提示只是默默不加載。后來我養(yǎng)成了習慣每次改完 MCP 配置先手動跑一遍 MCP 服務確認能啟動再集成到 Skill 里。5.5 Skill 維護成本怎么降Skill 寫多了維護成本會指數(shù)級上升。降低維護成本的核心是抽象和分層第一層是公共上下文所有 Skill 共享改一處生效全部。第二層是基礎 Skill只做單一職責的事比如讀實體類、寫文件。第三層是組合 Skill通過串聯(lián)基礎 Skill 完成復雜任務。這樣改基礎 Skill 的時候組合 Skill 自動受益不用挨個改。我實測下來做了分層之后維護 50 個 Skill 的成本大概相當于之前維護 15 個的成本。這個投入產出比還是很劃算的。5.6 幾個獨家避坑技巧最后分享幾個我踩坑踩出來的獨家技巧技巧一Skill 名稱用動詞開頭。比如generate-crud、parse-entity、validate-api這樣一看就知道這個 Skill 是干什么的。我早期用名詞命名比如crud-helper、entity-tool結果自己都記不清哪個是哪個。技巧二SKILL.md 里加示例。給每個 Skill 加一兩個輸入輸出示例Claude Code 看了示例之后輸出質量明顯提升。示例比描述管用這是我在寫了 40 多個 Skill 之后才總結出來的。技巧三定期清理廢棄 Skill。我每兩個月會盤一次 Skill 列表把三個月沒用過的 Skill 歸檔。Skill 不是越多越好多了反而會互相干擾。我現(xiàn)在保留的活躍 Skill 大概 20 個比 50 個的時候好用多了。技巧四用 Git 管理 Skill。Skill 也是代碼也該進版本控制。我用 Git 管理所有 SKILL.md每次改動都有記錄出問題能回滾還能看到演進歷史。技巧五Skill 的輸出盡量結構化。能用 JSON 就用 JSON能用表格就用表格避免大段自然語言。結構化輸出方便下游消費也方便你自己檢查。6. 我在實際項目里的落地體會聊了這么多方法論最后說點實際的。我在一個 Spring Boot MyBatis 的多商戶項目里用這套 Skill 體系做了完整的落地。項目大概有 30 多個實體類每個實體類都要生成 CRUD 模塊。用傳統(tǒng)方式一個模塊大概要半天用 Skill 串聯(lián)的方式一個模塊壓縮到 20 分鐘左右而且生成的代碼風格統(tǒng)一review 起來省心很多。但我也得說實話Skill 不是銀彈。它擅長的是重復性高、規(guī)則明確的任務對于需要創(chuàng)造性思考的任務Skill 反而會限制發(fā)揮。我現(xiàn)在的做法是重復性任務用 Skill 固化創(chuàng)造性任務還是手動做兩者結合效率最高。另外一點體會是寫 Skill 的過程本身就是梳理業(yè)務邏輯的過程。很多平時沒想清楚的細節(jié)在寫 SKILL.md 的時候被迫想清楚了。所以哪怕你最后不用這個 Skill寫的過程也是有價值的。如果你現(xiàn)在正準備寫第一個 Skill我的建議是別急著寫先花半小時想清楚觸發(fā)條件、輸入約定、邊界說明這三塊。這三塊想清楚了Skill 就成功了一半。至于執(zhí)行步驟反而是最容易補的。