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