1. 為什么 Skills 值得單獨拿出來講Claude Code 這個工具本身已經不算新鮮了終端里跑一個 CLI接上模型能讀文件、能改代碼、能執(zhí)行命令很多人拿它當會動手的聊天窗口用。但真正把它用出效率差距的往往不是模型本身而是Skills這一層。我自己的感受很直接剛上手那陣子我每次開新項目都要重復交代一堆東西——這個倉庫用 pnpm 不用 npm測試跑 vitest 不跑 jest提交信息按 conventional commits 寫別動 legacy 目錄下的文件。說一次兩次還行說二十次就煩了。Skills 解決的正是這個問題它把這些重復的、項目相關的、帶流程性的指令固化下來讓 Claude Code 在特定場景下自動加載而不是靠你每次手動喂。那為什么標題要強調從項目級切到全局因為絕大多數人第一次接觸 Skills都是被某個具體項目逼出來的——項目里有個.claude/skills目錄或者同事丟給你一個 skill 文件夾讓你放進去。用著用著你會發(fā)現有些 skill 是只對當前倉庫有意義的比如這個項目的部署流程而有些 skill 是你走到哪都想帶著的比如你的代碼審查習慣、你的提交信息規(guī)范、你偏好的調試套路。前者留在項目級后者就該搬到全局。這篇東西我打算把兩件事講透一是 Skills 到底怎么裝、目錄結構長什么樣、加載優(yōu)先級怎么算二是項目級和全局這兩種作用域怎么選、怎么遷移、遷移時有哪些坑。適合已經裝好 Claude Code、能跑起來但還沒系統(tǒng)用過 Skills 的人也適合用了一陣子但一直沒搞明白為什么我的 skill 有時候生效有時候不生效的人。先把一個前提說清楚Skills 的機制在不同版本里細節(jié)會有微調下面講的目錄約定和優(yōu)先級邏輯是基于我實際使用和官方文檔的常見實踐總結出來的你落地時以自己版本的claude --help和官方文檔為準。但核心思路是穩(wěn)定的skill 就是一份帶元信息的 Markdown 指令包放在約定目錄里由 Claude Code 按作用域和匹配規(guī)則決定要不要加載。2. Skills 的本質一份會被自動召回的指令包2.1 Skill 到底是什么和 CLAUDE.md 有什么區(qū)別很多人第一次看到 Skills會把它和CLAUDE.md搞混。兩者確實都是給模型看的文字但定位完全不同。CLAUDE.md是常駐上下文。只要你在項目根目錄它基本每次都會被讀進去內容偏向這個項目是什么、整體約定是什么。它的問題是寫多了會一直占上下文而且它是always on的不管你現在在干嘛它都在那兒。Skill 是按需召回。它有一個描述descriptionClaude Code 會根據你當前的任務、你輸入的內容判斷要不要把這個 skill 的內容加載進來。也就是說一個 skill 可以寫得很長很細但只要當前任務用不上它就不占你的上下文預算。這是它比CLAUDE.md更適合承載流程性知識的根本原因。打個比方CLAUDE.md像是貼在工位上的便簽抬頭就能看見Skill 像是抽屜里的操作手冊需要擰螺絲的時候才抽出來翻。你不會把所有手冊都攤在桌上但你希望需要的時候一伸手就能拿到。2.2 一個 skill 的最小結構一個 skill 本質上就是一個目錄里面至少有一個SKILL.md有些版本叫skill.md大小寫敏感問題后面會專門講。這個文件由兩部分組成YAML frontmatter和正文。frontmatter 里最關鍵的是兩個字段nameskill 的標識名通常用短橫線連接的小寫單詞比如commit-style、api-review。description一句話說明這個 skill 干什么、什么時候該用它。這個字段是自動召回的命門寫得含糊模型就不知道該不該加載。正文就是你真正想傳達的指令?？梢允且欢我?guī)范、一套步驟、一份檢查清單甚至是一堆示例。Markdown 格式隨便用標題、列表、代碼塊都行。--- name: commit-style description: 當用戶要求提交代碼、生成 commit message 或整理變更時使用。規(guī)定本倉庫的提交信息格式與拆分粒度。 --- 提交信息遵循 conventional commits - 類型限定為 feat / fix / refactor / docs / test / chore - 標題不超過 72 字符用中文描述做了什么 - 正文說明為什么改不重復改了什么 - 一次提交只做一件事混了多個關注點就拆開就這么簡單。沒有編譯、沒有依賴、沒有注冊表純文本。這也是它好用的地方——你隨時能改改完立刻生效不需要重啟什么服務個別版本需要重新進入會話后面講。2.3 為什么用 Markdown 而不是配置文件有人會問為什么不搞成 JSON 或者 YAML 配置非要 Markdown我的理解是skill 的內容是給模型讀的自然語言不是給程序解析的結構化數據。你要寫的是遇到 X 情況就按 Y 步驟做注意別踩 Z 坑這種東西用 Markdown 寫最自然模型也最容易理解。而且 Markdown 允許你塞代碼塊、表格、示例對話這些都是提升指令質量的手段。你完全可以在一個 skill 里放一段錯誤示范 vs 正確示范的對比模型看了之后執(zhí)行準確率會明顯上升。用 JSON 寫這些就很別扭。3. 安裝 Skills 的三種路徑3.1 手動放置最原始也最可控最直接的方式就是手動建目錄、寫文件。項目級的話在倉庫根目錄建.claude/skills/skill-name/SKILL.md全局的話在用戶主目錄下的~/.claude/skills/skill-name/SKILL.md。我一般用命令行快速搭骨架# 項目級 mkdir -p .claude/skills/commit-style touch .claude/skills/commit-style/SKILL.md # 全局 mkdir -p ~/.claude/skills/commit-style touch ~/.claude/skills/commit-style/SKILL.md然后拿編輯器把內容填進去。這種方式的好處是完全透明你知道每個文件在哪、內容是什么出問題好排查。壞處是分享麻煩得手動拷貝。注意目錄名和 frontmatter 里的name最好保持一致。有些版本會以目錄名為準有些以name為準不一致的時候行為可能讓你困惑。統(tǒng)一起來最省心。3.2 從他人項目或倉庫拷貝社區(qū)里已經有不少人把自己寫的 skill 整理成倉庫分享出來比如各種前端開發(fā) skills代碼審查 skills合集。用法通常就是把對應的 skill 目錄整個拷到你的.claude/skills/或~/.claude/skills/下?？截惖臅r候有幾個細節(jié)要盯檢查 frontmatter 是否完整。有些分享出來的 skill 只留了正文name和description被刪了直接放進去可能不生效。檢查有沒有硬編碼路徑。別人寫的 skill 里可能寫死了他自己機器的路徑比如/Users/xxx/projects/...你得改成自己的或者改成相對路徑。檢查語言和風格。如果 skill 正文是英文而你團隊用中文交流模型執(zhí)行時可能中英混雜讀起來別扭建議按需翻譯。3.3 用包管理或腳手架工具安裝隨著 Skills 生態(tài)起來也出現了一些輔助安裝的工具和腳手架。常見形態(tài)是npx一把梭或者某個 CLI 提供skills add之類的子命令。這類工具的價值在于批量安裝和版本管理適合你想一次性裝一套 skill 集合的場景。但這里有個坑要提醒全局安裝的包和全局 skill 是兩碼事。npm 的全局包npm install -g裝的是可執(zhí)行程序而 skill 是放在~/.claude/skills/下的文本目錄。有些工具會幫你把 skill 寫到正確位置有些只是裝了個 CLI你還得自己跑命令生成 skill。裝完先確認~/.claude/skills/下到底有沒有東西別以為裝了包就萬事大吉。卸載同理。如果你用npm uninstall -g卸了工具但 skill 目錄是工具之前寫進去的那些目錄不會自動消失得手動清。反過來如果你手動刪了 skill 目錄工具那邊可能還記著下次更新又給你寫回來。裝和卸都要兩頭確認。4. 項目級 vs 全局作用域怎么選4.1 兩種作用域的加載邏輯項目級 skill 放在倉庫的.claude/skills/下只在這個倉庫里生效。全局 skill 放在~/.claude/skills/下在你所有項目里都可見。當兩者存在同名 skill 時項目級通常優(yōu)先。這個設計很合理項目級代表這個倉庫的特殊約定全局代表我的通用習慣特殊應該覆蓋通用。比如你全局有個commit-style說用英文寫提交信息但某個倉庫要求中文你就在那個倉庫的項目級放一個同名 skill 覆蓋掉。實際加載時Claude Code 會把兩個作用域的 skill 都納入候選然后根據當前任務和 description 匹配度決定加載哪些。所以不是項目級存在就完全屏蔽全局而是同名沖突時項目級贏不同名的全局 skill 依然可用。4.2 什么該放項目級判斷標準很簡單這個 skill 的內容離開這個倉庫還成立嗎放項目級的典型內容這個項目的目錄結構和模塊劃分說明這個項目特有的構建、測試、部署命令這個項目的代碼風格約定比如某個老項目還在用特定 lint 規(guī)則這個項目的業(yè)務術語表模型不懂你們內部黑話這個項目的分支策略和發(fā)布流程這些東西對別的項目毫無意義甚至會產生誤導。你要是把A 項目的部署流程放到全局去 B 項目時模型可能真的照著 A 的流程給你操作那就出事了。4.3 什么該放全局全局 skill 承載的是你個人的工作習慣和方法論跨項目通用你的代碼審查清單不管什么語言你都會檢查的那幾項你的調試套路先看日志、再復現、再二分定位你的提交信息風格你偏好的解釋方式比如先給結論再給理由你常用的通用工具用法我自己的全局 skill 里有一個叫review-checklist的內容就是一份我每次 review 都會過一遍的清單邊界條件、錯誤處理、并發(fā)安全、日志埋點、測試覆蓋。不管我在哪個倉庫讓 Claude Code 幫我 review 時它都會參考這份清單省得我每次重新描述。4.4 一張表看清怎么選判斷維度放項目級放全局內容是否依賴具體倉庫是否是否涉及內部業(yè)務術語是否是否跨語言跨項目通用否是是否會被團隊其他人用到是隨倉庫共享否只屬于你是否包含個人偏好一般否是沖突時誰優(yōu)先優(yōu)先被覆蓋這張表不是死規(guī)矩但能覆蓋八成場景。拿不準的時候問自己一句我把這個 skill 帶到下一個完全無關的項目里它還有用嗎有用就全局沒用就項目級。5. 從項目級遷移到全局的完整操作5.1 遷移前的判斷這個 skill 真的通用嗎遷移不是簡單地把文件從 A 挪到 B。先做一次通用性體檢通讀 skill 正文把所有提到具體項目名、具體路徑、具體內部服務的地方標出來。判斷這些具體信息是必須保留還是可以抽象。比如調用deploy.sh部署到 staging是項目特有的得刪或改提交前跑一遍測試是通用的保留。把抽象后的版本寫出來確保它在任何項目里讀起來都成立。我踩過一次坑把一個寫了一半的 skill 直接挪到全局里面還留著參考src/legacy/下的實現。結果在別的項目里模型真的去找src/legacy/找不到就卡住還反過來問我這個目錄在哪。遷移前一定要把項目特有的引用清干凈。5.2 具體遷移步驟假設你要把項目里的commit-style遷到全局# 1. 先復制不要直接移動保留項目級作為備份 cp -r .claude/skills/commit-style ~/.claude/skills/ # 2. 編輯全局版本去掉項目特有內容 # 打開 ~/.claude/skills/commit-style/SKILL.md 修改 # 3. 確認全局版本沒問題后再決定項目級是否刪除 rm -rf .claude/skills/commit-style為什么先復制不先移動因為遷移過程中你很可能發(fā)現全局版本改壞了或者改完之后項目里反而需要保留一個定制版。先復制兩邊都在驗證完再刪安全。5.3 遷移后必須驗證的三件事第一確認加載生效。開一個新的 Claude Code 會話隨便觸發(fā)一下這個 skill 的場景看模型有沒有按 skill 里的約定來。比如commit-style就讓它生成一條提交信息看格式對不對。第二確認沒有和現有全局 skill 沖突。如果你全局已經有一個同名或功能重疊的 skill遷移過去會打架。先ls ~/.claude/skills/看一眼有重名的先合并或改名。第三確認項目里沒有殘留依賴。有些項目可能在CLAUDE.md里寫了提交規(guī)范見.claude/skills/commit-style你把目錄刪了這個引用就斷了。搜一下項目里有沒有指向這個 skill 的引用一并更新。5.4 遷移的時機選擇我的建議是先項目級用一段時間確認穩(wěn)定了再遷全局。剛寫出來的 skill 往往有問題description 寫得不準、步驟有遺漏、邊界沒考慮。在項目級小范圍試錯改起來沒心理負擔。等它在兩三個項目里都驗證過好用再遷全局。反過來如果你一上來就寫全局 skill改一次影響所有項目心理壓力大反而不敢改。而且全局 skill 多了之后description 之間的匹配會互相干擾模型可能加載了不該加載的 skill。全局 skill 要精項目級 skill 可以多這是我用下來的一個原則。6. 讓 Skill 真正被召回的寫法技巧6.1 description 是命門別糊弄skill 寫得好不好一半看 description。模型判斷要不要加載這個 skill主要靠它。寫得含糊比如description: 幫助處理代碼模型根本不知道什么時候該用等于白寫。好的 description 應該包含觸發(fā)場景和能力范圍差description: 代碼審查相關好description: 當用戶要求審查代碼、檢查 PR、或詢問某段代碼是否有問題時使用。覆蓋邊界條件、錯誤處理、并發(fā)安全、日志埋點四個維度。把什么時候用寫清楚比把是什么寫清楚更重要。你可以想象自己在給一個新人交代遇到這種情況你就翻這份文檔把這句話寫進 description。6.2 正文要具體到能執(zhí)行skill 正文最忌諱寫空話。注意代碼質量保持良好風格這種話模型看了等于沒看。要寫成可執(zhí)行的動作空話注意錯誤處理。具體每個可能失敗的外部調用都要有錯誤分支錯誤信息里必須包含調用參數和失敗原因禁止只寫console.log(error)。具體到這種程度模型執(zhí)行起來才有抓手。我寫 skill 的時候有個習慣每寫一條規(guī)則就問自己這條能不能被驗證。能被驗證的規(guī)則才是好規(guī)則。6.3 用示例錨定輸出格式如果 skill 涉及輸出格式直接給示例。比如你要模型生成特定格式的審查報告就在 skill 里放一段輸出格式示例 ## 問題清單 - [嚴重] 文件:行號 - 問題描述 - 建議改法 - [一般] 文件:行號 - 問題描述 - 建議改法 ## 總結 一句話說明整體質量。模型看到示例輸出會穩(wěn)定很多。這比用文字描述請按嚴重程度分級列出問題有效得多。6.4 控制單個 skill 的體量一個 skill 不要什么都往里塞。我見過有人把整個團隊的編碼規(guī)范、部署流程、測試策略全寫進一個 skill幾千字。結果就是要么模型加載了但抓不住重點要么因為太長反而不被召回。一個 skill 聚焦一件事。提交規(guī)范一個、代碼審查一個、調試流程一個。需要組合的時候讓它們各自被召回而不是揉成一坨。單個 skill 正文控制在幾百字到一千字出頭比較舒服超過兩千字就該考慮拆了。7. 常見問題與排查實錄7.1 skill 不生效從哪查起這是被問得最多的問題。我整理了一個排查順序按這個走基本能定位排查項怎么查常見原因文件位置對不對ls .claude/skills/或ls ~/.claude/skills/放錯目錄或少了.claude這一層文件名對不對確認是SKILL.md大小寫寫錯或寫成了skill.mdfrontmatter 完整嗎看開頭有沒有---包裹的name和description漏了 frontmatter或 YAML 格式錯誤description 夠具體嗎讀一遍問自己什么場景該用它太含糊模型匹配不上有沒有被同名覆蓋檢查項目級和全局有沒有重名項目級覆蓋了全局你以為在用全局會話是否刷新重開一個會話試試有些版本改動后需要新會話才生效我遇到最多的是文件名大小寫和frontmatter 缺失這兩個。尤其是從別人那兒拷來的 skill經常只剩正文frontmatter 被刪了放進去自然不生效。7.2 全局 skill 太多導致互相干擾全局 skill 裝多了之后會出現一種情況你明明想觸發(fā) A結果模型加載了 B或者兩個都加載了指令打架。解決辦法是精簡全局 skill 數量并且讓 description 之間的邊界清晰。如果兩個 skill 的 description 都寫著處理代碼相關問題它們必然互相干擾。把每個 skill 的適用范圍收窄比如一個專管提交信息一個專管代碼審查一個專管調試定位邊界清楚就不容易誤觸發(fā)。實在需要很多 skill 的時候考慮把它們合并成少數幾個大類 skill用正文里的小節(jié)區(qū)分場景。寧可少而精不要多而亂。7.3 遷移到全局后項目里反而不生效了這個情況通常是項目級殘留導致的。你遷到全局后項目里可能還留著一個舊的同名 skill項目級優(yōu)先于是模型加載的還是舊版本。檢查一下項目.claude/skills/下是不是還有同名目錄有就刪掉或更新。還有一種可能是項目級的CLAUDE.md里寫了和全局 skill 沖突的指令。CLAUDE.md是常駐的優(yōu)先級往往高于按需召回的 skill所以它里面的約定會蓋過 skill。檢查一下CLAUDE.md有沒有相關表述。7.4 團隊協(xié)作時怎么共享 skill項目級 skill 跟著倉庫走天然適合團隊共享。但要注意兩點一是別把個人偏好寫進項目級 skill。項目級是團隊共用的你個人的提交習慣、你偏好的解釋風格不該強加給所有人。這些放你自己的全局 skill 里。二是項目級 skill 要進版本控制。.claude/skills/目錄應該被 git 跟蹤這樣新同事 clone 下來就有。但要注意別把帶敏感信息的 skill 提交上去比如包含內部密鑰、內部地址的。提交前掃一眼內容。提示如果團隊對 skill 有爭議可以先在項目級試運行收集反饋再固化。別一上來就當成強制規(guī)范容易引起抵觸。7.5 幾個我踩過的具體坑坑一YAML 里的冒號。description 里如果寫了中文冒號或者英文冒號后面跟空格YAML 解析可能出錯。穩(wěn)妥做法是把 description 用引號包起來或者避免在值里用冒號?？佣形奈募?。有些系統(tǒng)對中文路徑支持不好skill 目錄名盡量用英文小寫加短橫線別用中文。坑三軟鏈接。有人為了一處修改多處生效把全局 skill 目錄軟鏈接到某個 git 倉庫。這招能用但要注意 Claude Code 讀取時是否跟隨軟鏈接不同版本行為可能不一樣。用之前先測一下?？铀母耐瓴簧Ь椭貑?。大部分情況下改 skill 內容不需要重啟但如果你改了目錄結構或者增刪了 skill重開一個會話是最穩(wěn)的驗證方式。別在舊會話里反復試浪費時間。8. 我個人的使用節(jié)奏和一些建議用到現在我的 skill 布局大概是這樣全局放了五六個都是跨項目通用的——提交規(guī)范、審查清單、調試流程、解釋風格、通用工具用法。項目級則看倉庫一般每個活躍項目兩三個都是這個項目特有的約定。我的遷移節(jié)奏是新東西先在項目級養(yǎng)養(yǎng)熟了再考慮升全局。一個 skill 我會在至少兩個不同項目里用過確認它不依賴具體上下文才挪到全局。挪的時候順手把 description 再打磨一遍因為全局的匹配范圍更廣description 得更精準。還有一點體會skill 不是越多越好是越準越好。我早期貪多全局塞了十幾個結果互相干擾模型經常加載錯。后來砍到五六個每個都打磨得邊界清晰反而效果好?，F在我加新全局 skill 很謹慎會先問自己這個真的每個項目都用得上嗎答案是否定的就留在項目級。最后分享一個我常用的小技巧給 skill 寫一個反例小節(jié)。比如提交規(guī)范 skill 里除了寫應該怎么寫再寫一段這些寫法是錯的把常見的錯誤格式列出來。模型看到反例執(zhí)行時會主動避開比只給正例效果好不少。這個技巧在審查類、格式類 skill 上尤其管用。至于后續(xù)還能怎么擴展我最近在試的是把 skill 和項目里的腳本結合起來——skill 里不只寫怎么做還寫調用哪個腳本做讓模型直接執(zhí)行現成的工具而不是每次現編命令。這條路還在摸索等跑順了再單獨聊。