1. 為什么你的 Claude Code 總是“重新學(xué)一遍”用 Claude Code 寫代碼的人大概率都經(jīng)歷過這種循環(huán)每次開新會話都要把同一套項目規(guī)范、同一套代碼風(fēng)格、同一套發(fā)布流程重新講一遍。講完這次下次換個窗口又得從頭來。提示詞越寫越長最后變成一份幾百行的“項目說明書”塞進對話里既占上下文又容易被模型忽略。問題的根源在于提示詞是會話級的而工作流是項目級的。你在一次對話里教會 Claude 的東西會話結(jié)束就沒了。Claude Skills 要解決的就是這件事——它把“怎么做一個特定任務(wù)”從一次性提示詞變成文件系統(tǒng)里可復(fù)用、可版本管理、可團隊共享的技能包。Claude Skills 是 Anthropic 推出的一套機制用一個SKILL.md文件注意大小寫Claude Code 里通常寫作SKILL.md加上可選的腳本和資源文件把某類任務(wù)的執(zhí)行方法固化下來。Claude Code 會在合適的時機自動發(fā)現(xiàn)并加載它你不需要手動“召喚”。它適合誰適合所有把 Claude Code 當(dāng)日常開發(fā)工具、并且發(fā)現(xiàn)自己反復(fù)寫同類提示詞的人——尤其是做數(shù)據(jù)清洗、文檔生成、代碼審查、發(fā)布流程自動化的開發(fā)者。我試過把一套“生成周報”的提示詞從對話里搬進 Skill之后每周只需要說一句“生成本周周報”Claude 就按固定格式、固定數(shù)據(jù)源、固定輸出路徑跑完。這篇文章就按這個思路從文件結(jié)構(gòu)講到觸發(fā)機制再給一份可直接復(fù)制的模板最后演示怎么驗證它真的生效。2. Claude Skills 的前置準(zhǔn)備目錄、模型與接入配置在動手寫SKILL.md之前先把運行環(huán)境理清楚。Claude Code 的 Skills 走的是文件系統(tǒng)發(fā)現(xiàn)路線和網(wǎng)頁版 claude.ai 上傳 ZIP 的方式完全不同。網(wǎng)頁版是“上傳—開關(guān)—自動激活”Claude Code 是“放進目錄—自動掃描—按描述激活”。理解這個差異后面排障會省很多事。Skills 有三個存放位置優(yōu)先級和用途不一樣位置路徑作用范圍典型用途個人 Skills~/.claude/skills/skill-name/當(dāng)前用戶所有項目個人通用工作流項目 Skills項目根/.claude/skills/skill-name/僅當(dāng)前項目團隊共享、隨 git 同步插件 Skills隨插件安裝自動提供取決于插件第三方能力擴展個人 Skills 適合放“我自己到哪都用”的東西比如統(tǒng)一的提交信息格式。項目 Skills 適合放“這個倉庫專屬”的東西比如本項目的 API 命名規(guī)范、數(shù)據(jù)庫遷移流程。團隊協(xié)作優(yōu)先用項目 Skills因為它能進 git別人git pull之后自動就有了。接下來是模型接入。Claude Code 需要能訪問 Claude 模型這里我用 TaoToken 做統(tǒng)一接入它的 API 地址是https://taotoken.net/api兼容 Anthropic 的接口格式。配置方式是在環(huán)境變量里指定 Base URL 和 KeyClaude Code 會讀取這些變量。# 寫入 shell 配置以 zsh 為例bash 換成 ~/.bashrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密鑰如果你用的是 Claude Code 的 settings 文件方式可以在~/.claude/settings.json里寫{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密鑰 } }Key 在 TaoToken 控制臺的 API Keys 頁面創(chuàng)建地址是https://taotoken.net/console/api-keys。創(chuàng)建后復(fù)制一次之后不再顯示。模型 ID 用 Claude 系列即可比如claude-sonnet-4-5這類標(biāo)識具體以控制臺模型列表為準(zhǔn)。這里有個容易踩的坑Base URL 結(jié)尾不要多加/v1。TaoToken 的接入地址就是https://taotoken.net/apiClaude Code 會自己拼接路徑。多寫一層會導(dǎo)致 404而不是 401報錯信息看起來像“模型不存在”實際是路徑錯了。配置完先別急著寫 Skill用一條最小請求確認(rèn)鏈路通curl https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d { model: claude-sonnet-4-5, max_tokens: 64, messages: [{role: user, content: 回復(fù) OK 兩個字母}] }返回里有content字段且文本是 OK說明接入沒問題。這一步過了再進 Skills 才不會把“接入錯誤”誤判成“Skill 沒生效”。3. 可復(fù)制的 SKILL.md 模板與目錄結(jié)構(gòu)現(xiàn)在進入正題。一個 Skill 的最小單元是一個目錄里面必須有SKILL.md。文件名在 Claude Code 里是大小寫敏感的寫成skill.md在部分版本上不會被識別統(tǒng)一用SKILL.md最穩(wěn)。先看目錄結(jié)構(gòu)。下面這個模板是我實際在用的“周報生成”Skill你可以直接復(fù)制改名.claude/skills/weekly-report/ ├── SKILL.md # 核心文件必需 ├── reference.md # 參考文檔可選 ├── scripts/ │ └── collect_git.py # 可執(zhí)行腳本可選 └── resources/ └── template.md # 模板資源可選SKILL.md必須以 YAML frontmatter 開頭兩個字段是必需的name和description。description是觸發(fā)決策的核心寫得好不好直接決定 Claude 會不會用它。--- name: weekly-report description: 根據(jù) git 提交記錄生成結(jié)構(gòu)化周報。當(dāng)用戶提到周報本周總結(jié)weekly report匯總本周提交時使用。輸出 Markdown 格式包含完成事項、進行中事項、風(fēng)險點三部分。 allowed-tools: - Read - Bash - Write --- # 周報生成技能 ## 何時使用 用戶要求生成周報、本周工作總結(jié)、或匯總一段時間內(nèi)的代碼提交時。 ## 執(zhí)行步驟 1. 運行 scripts/collect_git.py 收集最近 7 天的提交記錄 2. 按提交類型feat/fix/docs/refactor歸類 3. 讀取 resources/template.md 作為輸出模板 4. 將歸類結(jié)果填入模板輸出到 reports/weekly-YYYY-MM-DD.md ## 輸出要求 - 完成事項每條一行格式為 - [類型] 描述 - 進行中事項標(biāo)注當(dāng)前進度百分比 - 風(fēng)險點沒有則寫無 ## 注意事項 - 不要編造未在提交記錄中出現(xiàn)的內(nèi)容 - 提交信息為英文時保留原文不翻譯allowed-tools是可選的但強烈建議寫。它的作用是當(dāng)這個 Skill 激活時Claude 只能使用你列出的工具不需要每次請求權(quán)限。上面這個 Skill 只允許讀文件、跑 Bash、寫文件不會去動網(wǎng)絡(luò)或刪庫安全性可控。description的寫法有個訣竅同時寫“做什么”和“什么時候用”并塞進用戶可能說的關(guān)鍵詞。對比一下# 差的寫法太泛Claude 不知道何時觸發(fā) description: 幫助處理報告 # 好的寫法功能 觸發(fā)詞 輸出形態(tài) description: 根據(jù) git 提交記錄生成結(jié)構(gòu)化周報。當(dāng)用戶提到周報本周總結(jié)weekly report匯總本周提交時使用。輸出 Markdown 格式包含完成事項、進行中事項、風(fēng)險點三部分。差的寫法里沒有“周報”這個詞用戶說“幫我寫周報”時Claude 匹配不上。好的寫法把用戶可能用的詞都列進去了命中率高很多。再給一個更貼近編碼場景的模板做“代碼審查”--- name: code-review description: 對指定文件或 diff 做代碼審查檢查命名、錯誤處理、邊界條件、性能隱患。當(dāng)用戶說審查代碼review 一下看看這段有沒有問題code review時使用。 allowed-tools: - Read - Grep - Bash --- # 代碼審查技能 ## 審查維度 1. 命名變量/函數(shù)名是否表意清晰 2. 錯誤處理異常是否被吞掉是否有兜底 3. 邊界條件空值、越界、并發(fā)是否考慮 4. 性能是否有明顯的 N1、重復(fù)計算 ## 輸出格式 按嚴(yán)重程度分級BLOCKER / MAJOR / MINOR每條給出文件行號和修改建議。 ## 禁止 - 不要重寫整個文件只給針對性建議 - 不要對未改動的代碼提意見這兩個模板覆蓋了“生成類”和“審查類”兩種典型 Skill。你可以把它們放進.claude/skills/下對應(yīng)目錄重啟 Claude Code 會話即可被發(fā)現(xiàn)。4. 驗證 Skill 是否生效從發(fā)現(xiàn)到調(diào)用的完整請求寫完文件不等于生效。Claude Code 的 Skills 是按需加載的它不會把所有 Skill 內(nèi)容都塞進上下文而是先加載元數(shù)據(jù)name description判斷相關(guān)后再讀完整內(nèi)容。所以驗證要分兩步先確認(rèn)被發(fā)現(xiàn)再確認(rèn)被調(diào)用。第一步確認(rèn)發(fā)現(xiàn)。在 Claude Code 會話里直接問有哪些 Skills 可用正常情況下Claude 會列出它掃描到的 Skill 名稱和描述。如果沒看到你的 Skill先檢查路徑# 個人 Skills ls ~/.claude/skills/*/SKILL.md # 項目 Skills ls .claude/skills/*/SKILL.md兩個命令都要能列出你剛建的文件。列不出來就是路徑錯了常見的是把.claude寫成了claude或者目錄層級多套了一層。第二步確認(rèn)調(diào)用。構(gòu)造一個和description匹配的請求比如對周報 Skill幫我生成本周周報如果 Skill 生效Claude 會按SKILL.md里的步驟執(zhí)行先跑腳本收集提交再讀模板最后寫文件。你可以在輸出里看到它調(diào)用了scripts/collect_git.py并且生成了reports/weekly-2025-xx-xx.md。如果 Claude 沒有調(diào)用 Skill而是自己隨手寫了一段說明description沒匹配上。這時候不要改代碼先改描述。把用戶實際會說的那句話原封不動加進description的觸發(fā)詞里再試一次。驗證腳本類 Skill 時注意腳本的執(zhí)行權(quán)限chmod x .claude/skills/weekly-report/scripts/collect_git.py沒有執(zhí)行權(quán)限時Claude 調(diào)用會失敗報錯類似Permission denied。這個錯誤不會自動提示你“是權(quán)限問題”只會顯示腳本沒輸出容易誤判成 Skill 邏輯錯。還有一個驗證技巧讓 Claude 復(fù)述它加載了什么。在請求后追加一句執(zhí)行前先告訴我你加載了哪個 Skill以及它的執(zhí)行步驟。這樣你能看到它的“思考路徑”確認(rèn)它讀的是你的SKILL.md而不是憑記憶瞎編。這一步對調(diào)試description特別有用——如果它說“我沒有加載任何 Skill”那就是發(fā)現(xiàn)階段就失敗了。5. 常見報錯排查401、local proxy failed 與 Skill 不觸發(fā)Skills 本身不復(fù)雜但和接入層、文件系統(tǒng)疊在一起報錯信息往往指向錯誤的方向。下面按真實遇到的錯誤逐條拆。401 Unauthorized。這個幾乎都是 Key 的問題。先確認(rèn)環(huán)境變量真的被讀到了echo $ANTHROPIC_API_KEY echo $ANTHROPIC_BASE_URL如果輸出為空說明 shell 配置沒生效重新source ~/.zshrc或開新終端。如果 Key 有值但仍 401檢查是不是復(fù)制時帶了空格或換行。TaoToken 的 Key 在控制臺創(chuàng)建后只顯示一次如果丟了就重新建一個。local proxy failed / connection refused。這個報錯通常出現(xiàn)在你本地起了代理層但代理沒起來或端口不對。Claude Code 直連https://taotoken.net/api時不應(yīng)該出現(xiàn)這個錯。如果出現(xiàn)了檢查是不是在 settings 里額外配了HTTP_PROXY之類的變量把它清掉unset HTTP_PROXY HTTPS_PROXY ALL_PROXY然后重開會話。注意這里說的是清掉本地代理配置不是讓你去配代理方向別搞反。reading choices / 響應(yīng)解析失敗。這個多半是 Base URL 多寫了路徑。正確寫法是https://taotoken.net/api不要寫成https://taotoken.net/api/v1。多一層/v1后Claude Code 拼出來的完整路徑會變成/api/v1/v1/messages服務(wù)端返回的不是標(biāo)準(zhǔn)結(jié)構(gòu)客戶端解析choices字段時就報錯。改回正確地址即可。OAuth 相關(guān)報錯。如果你之前用官方賬號登錄過 Claude Code本地可能殘留 OAuth 憑據(jù)和 API Key 模式?jīng)_突。清理方式rm -rf ~/.claude/credentials.json然后重新用環(huán)境變量方式啟動。這一步會清掉登錄態(tài)之后走的就是純 API Key 鑒權(quán)。Skill 不觸發(fā)。這個不是報錯但最常被當(dāng)成 bug。排查順序先看description是否包含用戶實際會說的詞。用戶說“總結(jié)一下這周干了啥”你的描述里只有“周報”那就匹配不上。把口語化說法也加進去。再看 YAML 是否合法。frontmatter 必須以---開頭和結(jié)尾中間不能有 tab只能用空格。快速檢查head -n 15 .claude/skills/weekly-report/SKILL.md如果第一行不是---或者字段縮進用了 tabYAML 解析會靜默失敗Skill 等于不存在。最后看是否有多個 Skill 描述重疊。兩個 Skill 都寫“處理文檔”Claude 會猶豫。解決辦法是讓描述更具體把各自的觸發(fā)詞區(qū)分開。腳本報 ModuleNotFoundError。Claude Code 在加載 Skill 時可以按需安裝依賴但前提是腳本里聲明了。穩(wěn)妥做法是在SKILL.md里寫明依賴或者用標(biāo)準(zhǔn)庫寫腳本。比如collect_git.py只用subprocess和datetime就不需要額外安裝。6. 把重復(fù)提示詞沉淀成技能從單文件到 Agent Skills 組合單個 Skill 解決單個任務(wù)但真實工作流往往是多個任務(wù)的組合。比如“發(fā)布一個新版本”可能包含跑測試、生成 changelog、打 tag、發(fā)通知。這時候不需要寫一個巨大的 Skill而是拆成幾個小 Skill讓 Claude 自己組合。Claude Skills 的一個關(guān)鍵設(shè)計是Skill 之間不能顯式互相引用但 Claude 可以自動同時使用多個。這意味著你只要把每個 Skill 的description寫清楚Claude 在“發(fā)布版本”這個請求下會依次激活測試 Skill、changelog Skill、git tag Skill。這種組合能力就是 Agent Skills 的核心價值——把通用 Agent 變成懂你項目規(guī)矩的專用 Agent。組合時的組織建議按“動詞 對象”拆分而不是按“大流程”拆分。run-tests、gen-changelog、tag-release三個小 Skill 比一個release-everything更好維護也更容易復(fù)用——run-tests在本地開發(fā)時也能單獨用。共享資源放在項目根的資源目錄而不是每個 Skill 各存一份。比如 changelog 模板被兩個 Skill 用到就放在.claude/skills/shared/templates/在各自的SKILL.md里用相對路徑引用。用allowed-tools做權(quán)限隔離。生成 changelog 的 Skill 只需要Read和Write就不要給它Bash。這樣即使描述被誤觸發(fā)也不會執(zhí)行危險命令。版本管理上項目 Skills 直接進 git。團隊成員git pull后Claude Code 下次啟動就會掃描到新 Skill不需要額外安裝步驟。個人 Skills 則適合放那些“只對我自己有意義”的東西比如我自己的提交信息風(fēng)格。最后說一個實際體會Skill 的價值不在于寫得多而在于寫得準(zhǔn)。我一開始建了七八個 Skill結(jié)果描述互相重疊Claude 經(jīng)常選錯。后來砍到三個每個的description都精確到“用戶會說的原話”觸發(fā)準(zhǔn)確率反而上去了。先從一個最痛的點開始把它跑通、跑穩(wěn)再考慮擴展。當(dāng)你能用一句“生成本周周報”替代過去三百字的提示詞時這套機制就算真正落地了。