1. 從重復(fù)提示詞到可復(fù)用工作流Claude Code Skill 到底解決什么問題如果你已經(jīng)在用 Claude Code 寫代碼大概率經(jīng)歷過這樣的場(chǎng)景每次讓 Claude 做代碼審查都要重新描述一遍檢查命名規(guī)范、看有沒有空指針、注意 SQL 注入、輸出按嚴(yán)重程度分級(jí)每次整理文檔格式都要把同一套排版要求再打一遍。提示詞越寫越長(zhǎng)結(jié)果卻每次都不太一樣。Claude Code Skill 就是沖著這個(gè)痛點(diǎn)來的。簡(jiǎn)單說Skill 是 Claude Code 的專業(yè)技能包——把一段固定的工作流程、一套標(biāo)準(zhǔn)化的操作步驟固化成一個(gè)可以被斜杠命令調(diào)用的模塊。你輸入/reviewClaude 就按預(yù)設(shè)的審查流程走你說幫我做一下安全檢查它識(shí)別到意圖后自動(dòng)觸發(fā)security-review。整個(gè)過程不需要你每次重寫提示詞。它適合誰三類人最受益。第一類是團(tuán)隊(duì)里負(fù)責(zé)制定規(guī)范的開發(fā)者可以把團(tuán)隊(duì)的代碼風(fēng)格、文檔格式、部署檢查清單寫成 Skill讓所有人用同一個(gè)命令調(diào)用。第二類是經(jīng)常重復(fù)同類任務(wù)的個(gè)人開發(fā)者比如每天都要生成接口文檔、跑一遍數(shù)據(jù)校驗(yàn)。第三類是想把 AI 能力產(chǎn)品化的團(tuán)隊(duì)Skill 提供了一種提示詞即配置的工程化路徑。Skill 的核心載體是一個(gè)叫SKILL.md的文件。它由兩部分組成頂部的 YAML frontmatter 定義名稱、觸發(fā)描述、可用工具等元信息下面的 Markdown 正文寫具體執(zhí)行步驟。Claude Code 啟動(dòng)時(shí)會(huì)掃描~/.claude/skills/全局和項(xiàng)目根目錄下的.claude/skills/項(xiàng)目級(jí)保存即熱重載不用重啟。這里有個(gè)關(guān)鍵點(diǎn)Skill 的觸發(fā)依賴description字段。它承擔(dān)雙重角色——既是你輸入/時(shí)看到的菜單說明也是 Claude 判斷用戶這句話該不該自動(dòng)調(diào)用這個(gè) Skill的依據(jù)。所以 description 要寫成觸發(fā)條件式的第三人稱描述比如 This skill should be used when the user asks to...而不是簡(jiǎn)單寫代碼審查工具。理解了這層機(jī)制接下來就要解決一個(gè)繞不開的問題Skill 執(zhí)行時(shí)要調(diào)用模型Key 和 API 通道怎么統(tǒng)一管理。下面進(jìn)入實(shí)操。2. 接入前的準(zhǔn)備用 TaoToken 統(tǒng)一 Key 與 API 通道寫 Skill 之前先把模型調(diào)用的通道理順。Claude Code 本身需要配置 API 才能工作而 Skill 在執(zhí)行過程中會(huì)頻繁發(fā)起模型請(qǐng)求。如果每個(gè)項(xiàng)目、每臺(tái)機(jī)器都單獨(dú)配 Key管理成本會(huì)很高團(tuán)隊(duì)協(xié)作時(shí)更容易出現(xiàn)我這能跑你那報(bào) 401的情況。TaoToken 在這里的角色是統(tǒng)一入口一個(gè) Key 覆蓋多種模型調(diào)用Base URL 固定團(tuán)隊(duì)里所有人用同一套配置。官網(wǎng)地址是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 端點(diǎn)是 https://taotoken.net/api 。配置 Claude Code 時(shí)核心是三件套Base URL、API Key、Model ID。這三者缺一不可后面排查報(bào)錯(cuò)時(shí)也主要圍繞它們展開。先拿 Key。登錄后進(jìn)入控制臺(tái)在 API Keys 頁面創(chuàng)建一個(gè)新 Key。建議按用途命名比如claude-code-dev、skill-team-shared方便后續(xù)輪換和審計(jì)。創(chuàng)建后立即復(fù)制保存頁面刷新后就看不到了。拿到 Key 之后配置 Claude Code 的環(huán)境變量。在~/.zshrc或~/.bashrc里加上export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key保存后執(zhí)行source ~/.zshrc讓配置生效。如果你用的是 Claude Code 的 settings.json 方式也可以寫在配置文件里效果一樣。這里要提醒一點(diǎn)Base URL 后面不要手動(dòng)加/v1之類的路徑TaoToken 的端點(diǎn)已經(jīng)處理好路由。我見過有人畫蛇添足加上/v1/messages結(jié)果一直報(bào) 404。配置完成后先別急著寫 Skill用一條最簡(jiǎn)單的請(qǐng)求驗(yàn)證通道是否打通。這一步很重要因?yàn)槿绻A(chǔ)通道有問題后面 Skill 調(diào)試時(shí)你會(huì)分不清是 Skill 寫錯(cuò)了還是 Key 配錯(cuò)了。驗(yà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-20250514, max_tokens: 100, messages: [{role: user, content: 回復(fù) OK 兩個(gè)字母}] }如果返回里能看到content字段和正常的文本說明通道沒問題。如果報(bào) 401檢查 Key 是否復(fù)制完整、有沒有多余空格。如果報(bào)連接失敗檢查 Base URL 拼寫。通道打通后再回到 Skill 本身。因?yàn)?Skill 執(zhí)行時(shí)會(huì)復(fù)用這套環(huán)境變量所以只要這里通了Skill 里的模型調(diào)用就不會(huì)因?yàn)檎J(rèn)證問題卡住。對(duì)于需要長(zhǎng)期跑編碼任務(wù)或 Agent 工作流的場(chǎng)景可以考慮用 Coding Plan它在調(diào)用額度和并發(fā)上有更合適的配置。如果只是想先驗(yàn)證模型對(duì)話效果用模型對(duì)話頁面直接測(cè)試更輕量。3. 可復(fù)制配置SKILL.md 模板與目錄結(jié)構(gòu)現(xiàn)在進(jìn)入核心部分。我會(huì)給出一個(gè)完整的自定義 Skill 示例從目錄結(jié)構(gòu)到 SKILL.md 內(nèi)容再到 settings 配置全部可以直接復(fù)制使用。先看目錄結(jié)構(gòu)。假設(shè)我們要做一個(gè)接口文檔生成的 Skill名字叫api-doc-gen~/.claude/skills/ └── api-doc-gen/ ├── SKILL.md └── scripts/ └── extract_routes.py全局 Skill 放在~/.claude/skills/所有項(xiàng)目都能用。如果只想在某個(gè)項(xiàng)目里生效放到項(xiàng)目根目錄的.claude/skills/下。名稱沖突時(shí)項(xiàng)目級(jí)優(yōu)先。SKILL.md 的內(nèi)容如下--- name: api-doc-gen description: This skill should be used when the user asks to 生成接口文檔 or 導(dǎo)出 API 文檔 or 整理路由說明. It scans route definitions and produces a Markdown API reference. version: 1.0.0 model: sonnet allowed-tools: Read, Write, Bash(python:*), Glob argument-hint: [source-dir] user-invocable: true --- # 接口文檔生成 Skill ## 執(zhí)行步驟 1. 使用 Glob 掃描 $ARGUMENTS 指定目錄下的所有路由文件匹配模式 **/*route*.{js,ts,py} 2. 對(duì)每個(gè)匹配文件用 Read 讀取內(nèi)容提取 HTTP 方法、路徑、參數(shù)、返回值結(jié)構(gòu) 3. 調(diào)用 scripts/extract_routes.py 做結(jié)構(gòu)化解析輸出 JSON 中間結(jié)果 4. 將 JSON 轉(zhuǎn)換為 Markdown 表格包含方法、路徑、參數(shù)、返回示例 5. 寫入 docs/API.md如果文件已存在則追加到末尾并標(biāo)注生成時(shí)間 ## 輸出格式要求 - 每個(gè)接口一個(gè)三級(jí)標(biāo)題 - 參數(shù)用表格呈現(xiàn)必填項(xiàng)加粗 - 返回示例用 json 代碼塊 - 文件末尾附生成時(shí)間戳frontmatter 里幾個(gè)字段值得說明。model指定用哪個(gè)模型可選 sonnet、opus、haiku不寫就用默認(rèn)。allowed-tools限定這個(gè) Skill 能用的工具比如這里只允許讀文件、寫文件、跑 Python 腳本避免它誤執(zhí)行危險(xiǎn)命令。argument-hint是參數(shù)提示輸入/api-doc-gen時(shí)會(huì)顯示[source-dir]提醒你傳目錄。user-invocable設(shè)為 false 時(shí)Skill 不會(huì)出現(xiàn)在斜杠菜單里只能靠自動(dòng)觸發(fā)。配套的scripts/extract_routes.py可以很簡(jiǎn)單import json import re import sys def extract(filepath): with open(filepath, encodingutf-8) as f: content f.read() routes [] pattern r(get|post|put|delete)\s*\(\s*[\]([^\])[\] for match in re.finditer(pattern, content, re.IGNORECASE): routes.append({ method: match.group(1).upper(), path: match.group(2), source: filepath }) return routes if __name__ __main__: result [] for path in sys.argv[1:]: result.extend(extract(path)) print(json.dumps(result, ensure_asciiFalse, indent2))如果你用 settings.json 管理 Claude Code 配置可以這樣寫{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key }, skills: { autoLoad: true, directories: [ ~/.claude/skills, .claude/skills ] } }這個(gè)配置放在~/.claude/settings.json。autoLoad打開后Skill 目錄里的改動(dòng)會(huì)熱重載保存 SKILL.md 立即生效不用重啟 Claude Code。配置寫完后輸入/api-doc-gen src/routes就能調(diào)用。如果 Skill 沒出現(xiàn)在菜單里先檢查目錄名和name字段是否一致再確認(rèn)user-invocable沒被設(shè)成 false。4. 驗(yàn)證請(qǐng)求與成功結(jié)果新增、調(diào)試、驗(yàn)證一個(gè) Skill配置寫好了接下來走一遍完整的驗(yàn)證流程。我會(huì)用一個(gè)更簡(jiǎn)單的 Skill 來演示方便你跟著做。新建一個(gè) Skill 叫l(wèi)ine-counter功能是統(tǒng)計(jì)指定目錄下 Python 文件的行數(shù)并輸出報(bào)告。第一步建目錄mkdir -p ~/.claude/skills/line-counter第二步寫 SKILL.md--- name: line-counter description: This skill should be used when the user asks to 統(tǒng)計(jì)代碼行數(shù) or count lines or 看看有多少行代碼. version: 1.0.0 allowed-tools: Glob, Read, Bash(wc:*) argument-hint: [directory] --- # 代碼行數(shù)統(tǒng)計(jì) 1. 用 Glob 掃描 $ARGUMENTS 目錄下所有 .py 文件 2. 對(duì)每個(gè)文件執(zhí)行 wc -l 統(tǒng)計(jì)行數(shù) 3. 匯總總行數(shù)、文件數(shù)、平均行數(shù) 4. 按行數(shù)從多到少排序輸出第三步保存。Claude Code 會(huì)自動(dòng)掃描到新 Skill。第四步驗(yàn)證。在 Claude Code 里輸入/line-counter src預(yù)期看到類似輸出掃描目錄src 找到 12 個(gè) Python 文件 總行數(shù)1847 平均行數(shù)153.9 按行數(shù)排序 1. src/core/engine.py - 412 行 2. src/api/handlers.py - 287 行 ...如果輸出符合預(yù)期說明 Skill 生效了。這時(shí)候可以再測(cè)試自動(dòng)觸發(fā)直接輸入幫我統(tǒng)計(jì)一下 src 目錄的代碼行數(shù)Claude 應(yīng)該識(shí)別到 description 匹配自動(dòng)調(diào)用這個(gè) Skill不需要你輸入斜杠命令。再測(cè)一個(gè)帶參數(shù)的場(chǎng)景。輸入/line-counter tests看它是否正確切換到 tests 目錄。如果參數(shù)沒傳進(jìn)去檢查 SKILL.md 里是否用了$ARGUMENTS占位符。調(diào)試技巧如果 Skill 執(zhí)行到一半卡住或結(jié)果不對(duì)按 Esc 中斷然后檢查 SKILL.md 的步驟描述是否足夠明確。Claude 是按 Markdown 正文的步驟執(zhí)行的步驟寫得越具體執(zhí)行越穩(wěn)定。比如統(tǒng)計(jì)行數(shù)不如對(duì)每個(gè)文件執(zhí)行 wc -l 并記錄返回值來得可靠。驗(yàn)證模型調(diào)用是否走了 TaoToken 通道可以在 Skill 執(zhí)行時(shí)觀察是否有認(rèn)證報(bào)錯(cuò)。如果 Skill 能正常跑完說明 Base URL 和 Key 配置正確。想單獨(dú)驗(yàn)證模型對(duì)話可以用模型對(duì)話頁面發(fā)一條測(cè)試消息確認(rèn)返回正常。對(duì)于需要反復(fù)調(diào)試的 Skill建議先用小范圍數(shù)據(jù)測(cè)試比如只掃一個(gè)文件確認(rèn)流程通了再擴(kuò)大范圍。這樣出問題時(shí)容易定位是解析邏輯錯(cuò)了還是文件匹配錯(cuò)了。5. 常見報(bào)錯(cuò)排查401、local proxy failed、reading choices、OAuthSkill 用起來之后報(bào)錯(cuò)是難免的。下面整理幾類高頻問題對(duì)照著排查。401 Unauthorized這是最常見的認(rèn)證錯(cuò)誤。表現(xiàn)是 Skill 執(zhí)行到模型調(diào)用那一步就中斷提示 401。原因通常是三個(gè)Key 復(fù)制不完整、Key 前后有空格、環(huán)境變量沒生效。排查步驟先echo $ANTHROPIC_API_KEY看輸出是否完整。如果為空說明source沒執(zhí)行或?qū)戝e(cuò)了文件。如果有值但報(bào) 401去控制臺(tái)確認(rèn)這個(gè) Key 是否被禁用或刪除。還有一種情況是 Base URL 寫成了https://taotoken.net/api/帶尾斜杠某些客戶端會(huì)拼出雙斜杠導(dǎo)致認(rèn)證失敗去掉尾斜杠即可。local proxy failed這個(gè)報(bào)錯(cuò)通常出現(xiàn)在網(wǎng)絡(luò)層。表現(xiàn)是請(qǐng)求發(fā)不出去提示連接本地代理失敗。檢查環(huán)境里有沒有設(shè)置HTTP_PROXY或HTTPS_PROXY指向一個(gè)不存在的本地端口。如果有unset掉再試。另外檢查ANTHROPIC_BASE_URL是否被其他配置覆蓋了比如 settings.json 和 shell 環(huán)境變量同時(shí)存在且值不同以 settings.json 為準(zhǔn)。reading choices 相關(guān)報(bào)錯(cuò)這類錯(cuò)誤一般出現(xiàn)在響應(yīng)解析階段提示讀取choices字段失敗。原因是返回結(jié)構(gòu)不符合預(yù)期可能是模型名寫錯(cuò)了導(dǎo)致返回了錯(cuò)誤信息體。檢查 SKILL.md 里的model字段確認(rèn)寫的是有效模型 ID。如果用的是自定義腳本解析響應(yīng)確認(rèn)腳本里取的字段路徑和實(shí)際返回一致。OAuth 相關(guān)報(bào)錯(cuò)如果你之前用 OAuth 方式登錄過 Claude Code環(huán)境里可能殘留了 OAuth token和 API Key 方式?jīng)_突。表現(xiàn)是提示 token 無效或認(rèn)證方式不匹配。解決辦法是清理舊的認(rèn)證緩存通常在~/.claude/目錄下找到認(rèn)證相關(guān)文件刪除然后重新用 API Key 配置。Skill 不觸發(fā)輸入斜杠命令沒反應(yīng)或者自然語言描述后沒自動(dòng)調(diào)用。先確認(rèn) Skill 名稱拼寫必須是小寫字母加連字符security-review不能寫成security_review。再檢查user-invocable是否為 true。自動(dòng)觸發(fā)不靈的話優(yōu)化 description寫成明確的觸發(fā)條件句式Claude 匹配準(zhǔn)確率會(huì)高很多。Skill 執(zhí)行結(jié)果不穩(wěn)定同一個(gè) Skill 每次輸出格式不一樣。這通常是步驟描述太模糊導(dǎo)致的。把 Markdown 正文里的步驟拆細(xì)每一步都寫清楚輸入是什么、輸出是什么、用什么工具。必要時(shí)把復(fù)雜邏輯抽到獨(dú)立腳本里Skill 只負(fù)責(zé)調(diào)用腳本這樣結(jié)果更可控。排查時(shí)有個(gè)通用思路先確認(rèn)基礎(chǔ)通道用 curl 測(cè) API再確認(rèn) Skill 是否被加載看/skills列表最后確認(rèn)執(zhí)行邏輯看步驟描述。逐層排除比盲目改配置高效。6. 把 Skill 用起來從單點(diǎn)工具到團(tuán)隊(duì)能力寫到這里Skill 的完整鏈路已經(jīng)跑通了從 SKILL.md 的結(jié)構(gòu)到目錄配置到新增調(diào)試再到報(bào)錯(cuò)排查。剩下的就是怎么把它變成團(tuán)隊(duì)里真正復(fù)用的東西。一個(gè)實(shí)用建議把團(tuán)隊(duì)共用的 Skill 放在項(xiàng)目倉庫的.claude/skills/下跟著代碼一起版本管理。新人 clone 下來就能用不用口頭傳授我們審查代碼要看哪幾點(diǎn)。個(gè)人常用的放全局目錄跨項(xiàng)目復(fù)用。Skill 的 description 值得反復(fù)打磨。它不只是給人看的說明更是 Claude 判斷觸發(fā)時(shí)機(jī)的依據(jù)。寫完一個(gè) Skill 后用幾種不同的自然語言描述測(cè)試自動(dòng)觸發(fā)看命中率如何不理想就調(diào)整措辭。模型調(diào)用通道方面統(tǒng)一用 TaoToken 的 Key 和 Base URL團(tuán)隊(duì)里不用各自申請(qǐng)。需要看調(diào)用情況就去控制臺(tái)需要新建或輪換 Key 就去 API Keys 頁面。如果 Skill 要接入更復(fù)雜的 Agent 工作流Coding Plan 在長(zhǎng)任務(wù)場(chǎng)景下更合適。接入文檔里有各語言 SDK 的配置示例照著改 Base URL 和 Key 就行。最后留一個(gè)可操作的動(dòng)作挑一個(gè)你每周至少重復(fù)三次的提示詞把它寫成 SKILL.md放到~/.claude/skills/下用一周看看能省多少時(shí)間。這比讀十篇教程都管用。