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