1. 為什么 SKILL.md 值得單獨(dú)拿出來(lái)講如果你已經(jīng)在用 Claude Code 或者 Codex 寫(xiě)代碼大概率遇到過(guò)這種情況模型很能寫(xiě)但寫(xiě)著寫(xiě)著就跑偏了。你讓它加個(gè)過(guò)濾功能它順手把狀態(tài)管理重構(gòu)了一遍你讓它修個(gè) bug它給你換了個(gè)框架。問(wèn)題不在模型能力而在于你從來(lái)沒(méi)告訴它「按什么流程干活」。mattpocock/skills 這個(gè)倉(cāng)庫(kù)解決的就是這件事。它不是往上下文里塞一大坨 prompt而是把工程實(shí)踐拆成一組小而明確的技能文件每個(gè)技能就是一個(gè) SKILL.md。你可以把它理解成給 AI 編程助手裝了一套「默認(rèn)工作紀(jì)律」先澄清需求再設(shè)計(jì)再 TDD再診斷最后收尾。SKILL.md 是這套機(jī)制的核心載體。它本質(zhì)上是一個(gè)帶 YAML frontmatter 的 Markdown 文件放在特定目錄下AI 編程助手啟動(dòng)時(shí)會(huì)掃描這些文件把技能注冊(cè)成可調(diào)用的命令。Claude Code 走的是.claude/skills/目錄Codex 走的是~/.codex/skills/或項(xiàng)目級(jí).codex/skills/。目錄放對(duì)了重啟工具技能就能用/技能名的方式觸發(fā)。這篇文章面向的是想快速跑通第一個(gè)技能示例的人。我會(huì)給出可復(fù)制的目錄結(jié)構(gòu)、SKILL.md 配置片段、一次完整的調(diào)用驗(yàn)證動(dòng)作以及怎么通過(guò) TaoToken 統(tǒng)一 Key 和 API 通道完成模型側(cè)接入。不繞彎子直接上手。2. SKILL.md 結(jié)構(gòu)解析與 mattpocock/skills 安裝路徑先說(shuō) SKILL.md 到底長(zhǎng)什么樣。一個(gè)標(biāo)準(zhǔn)的技能文件由兩部分組成頂部的 YAML frontmatter 和下面的 Markdown 正文。frontmatter 里至少要寫(xiě)name和descriptionname決定你調(diào)用時(shí)敲什么命令description決定模型什么時(shí)候會(huì)主動(dòng)想起這個(gè)技能。--- name: tdd description: 紅綠重構(gòu)工作流。當(dāng)用戶要求實(shí)現(xiàn)新功能或修復(fù) bug 時(shí)使用先寫(xiě)失敗測(cè)試再寫(xiě)最小實(shí)現(xiàn)最后重構(gòu)。 --- # TDD 技能 ## 工作流程 1. 先寫(xiě)一個(gè)失敗的測(cè)試證明目標(biāo)行為尚未實(shí)現(xiàn) 2. 運(yùn)行測(cè)試確認(rèn)它確實(shí)失敗 3. 寫(xiě)最小實(shí)現(xiàn)讓測(cè)試通過(guò) 4. 在測(cè)試保護(hù)下重構(gòu) 5. 重復(fù)上述步驟 ## 約束 - 不允許在沒(méi)有失敗測(cè)試的情況下寫(xiě)實(shí)現(xiàn)代碼 - 每次只處理一個(gè)行為 - 測(cè)試通過(guò)前不重構(gòu)這個(gè)結(jié)構(gòu)看起來(lái)簡(jiǎn)單但有幾個(gè)坑要注意。name只能用字母、數(shù)字和連字符不能用中文或空格。description要寫(xiě)清楚「什么時(shí)候用」而不是「這是什么」因?yàn)槟Ｐ褪强?description 做技能路由的。正文部分建議用步驟化的寫(xiě)法模型執(zhí)行時(shí)更穩(wěn)。mattpocock/skills 倉(cāng)庫(kù)里的技能都遵循這個(gè)結(jié)構(gòu)。倉(cāng)庫(kù)里比較常用的幾個(gè)技能包括grill-me負(fù)責(zé)先把需求問(wèn)清楚grill-with-docs在澄清需求時(shí)順便建立項(xiàng)目語(yǔ)言和文檔tdd走紅綠重構(gòu)diagnose做系統(tǒng)化排查to-prd把上下文整理成 PRDzoom-out先看全局再看局部improve-codebase-architecture收斂面條化代碼庫(kù)setup-matt-pocock-skills給當(dāng)前倉(cāng)庫(kù)做基礎(chǔ)配置。安裝方式分兩條路。Claude Code 和部分支持 skills 協(xié)議的工具可以用 npx 一鍵安裝npx skillslatest add mattpocock/skills執(zhí)行后工具會(huì)交互式問(wèn)你兩個(gè)問(wèn)題要安裝哪些 skills要裝到哪個(gè) coding agent。這里有個(gè)關(guān)鍵點(diǎn)一定要把setup-matt-pocock-skills一起選上。后面很多工程類技能都依賴它先把倉(cāng)庫(kù)級(jí)配置補(bǔ)齊比如 issue tracker 用哪個(gè)、triage 時(shí)打什么標(biāo)簽、生成的文檔放哪里。沒(méi)有這層配置to-issues、triage、diagnose這些技能會(huì)變成「看起來(lái)能用實(shí)際上上下文不統(tǒng)一」。Codex 不走 npx 一鍵安裝而是手動(dòng)把需要的 SKILL.md 復(fù)制到對(duì)應(yīng)目錄。Codex 的技能目錄是~/.codex/skills/全局或項(xiàng)目根目錄下的.codex/skills/項(xiàng)目級(jí)。復(fù)制完重啟 Codex 生效。你也可以直接給 Codex 發(fā)提示詞讓它自己裝安裝技能 https://github.com/mattpocock/skills 到 codex 中如果你不想一次裝全套可以只裝單個(gè)技能npx skillslatest add mattpocock/skills/tdd npx skillslatest add mattpocock/skills/diagnose建議先從setup-matt-pocock-skills、grill-me、tdd這三個(gè)開(kāi)始別一口氣把全部流程塞進(jìn)去。裝太多技能反而會(huì)讓模型在路由時(shí)猶豫。3. 可復(fù)制配置SKILL.md 目錄結(jié)構(gòu)與 TaoToken 接入片段這一節(jié)給你可以直接抄的配置。先看目錄結(jié)構(gòu)Claude Code 和 Codex 的路徑不一樣別放錯(cuò)。Claude Code 項(xiàng)目級(jí)技能目錄your-project/ ├── .claude/ │ └── skills/ │ ├── setup-matt-pocock-skills/ │ │ └── SKILL.md │ ├── grill-me/ │ │ └── SKILL.md │ ├── tdd/ │ │ └── SKILL.md │ └── diagnose/ │ └── SKILL.md ├── src/ └── package.jsonCodex 項(xiàng)目級(jí)技能目錄your-project/ ├── .codex/ │ └── skills/ │ ├── grill-me/ │ │ └── SKILL.md │ └── tdd/ │ └── SKILL.md ├── src/ └── package.json注意每個(gè)技能是獨(dú)立子目錄SKILL.md 放在子目錄里不是直接堆在 skills 根目錄下。這個(gè)層級(jí)關(guān)系搞錯(cuò)的話工具掃描不到。接下來(lái)是模型側(cè)接入。Claude Code 和 Codex 都需要一個(gè) API 通道來(lái)調(diào)用模型TaoToken 提供統(tǒng)一的 Key 和 Base URL省得你在多個(gè)工具之間來(lái)回切換配置。Claude Code 的配置文件在~/.claude/settings.json寫(xiě)入以下內(nèi)容{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: 你的TaoToken Key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }Codex 的配置走~/.codex/auth.json和~/.codex/config.toml兩個(gè)文件。auth.json存 Key{ OPENAI_API_KEY: 你的TaoToken Key }config.toml指定 Base URL 和模型model gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api wire_api responses三件套要寫(xiě)全Base URL、Key、Model ID。少任何一個(gè)都會(huì)在請(qǐng)求時(shí)報(bào)錯(cuò)。Key 在 TaoToken 控制臺(tái)的 API Keys 頁(yè)面生成生成后復(fù)制到上面兩個(gè)配置里。模型 ID 根據(jù)你實(shí)際用的模型填Claude 系列和 GPT 系列都支持。如果你用的是 Cline 或者帶 MCP 的工具配置邏輯一樣把 Base URL 指向https://taotoken.net/apiKey 填 TaoToken 的 KeyModel ID 填你要用的模型。Cline 的 MCP 配置里provider 選 OpenAI CompatibleBase URL 和 Key 按上面填。配置改完記得重啟工具。Claude Code 和 Codex 都是啟動(dòng)時(shí)讀配置熱改不生效。4. 驗(yàn)證請(qǐng)求跑通第一個(gè)技能調(diào)用配置寫(xiě)完了得驗(yàn)證一下到底通沒(méi)通。分兩步走先驗(yàn)證模型通道再驗(yàn)證技能調(diào)用。先驗(yàn)證模型通道。在 Claude Code 里直接發(fā)一句話你好請(qǐng)回復(fù)通道正常四個(gè)字如果返回了「通道正常」說(shuō)明 Base URL 和 Key 都對(duì)了。如果報(bào) 401說(shuō)明 Key 有問(wèn)題如果報(bào)連接失敗說(shuō)明 Base URL 寫(xiě)錯(cuò)了。這一步過(guò)了再往下走。接著驗(yàn)證技能是否注冊(cè)成功。在 Claude Code 里輸入/看補(bǔ)全列表里有沒(méi)有setup-matt-pocock-skills、grill-me、tdd這些命令。有的話說(shuō)明 SKILL.md 被正確掃描到了。Codex 里輸入/skills可以列出已注冊(cè)的技能。然后跑一次完整調(diào)用。用一個(gè)最小的 todo 項(xiàng)目演示。先執(zhí)行初始化技能/setup-matt-pocock-skills它會(huì)問(wèn)你幾個(gè)基礎(chǔ)問(wèn)題issue tracker 用 GitHub、Linear 還是本地文件triage 時(shí)給 issue 打什么標(biāo)簽生成的文檔存放在哪里。按你的實(shí)際情況回答。這一步的價(jià)值在于把倉(cāng)庫(kù)的工作方式固定下來(lái)后面to-issues、triage、diagnose都會(huì)直接吃這些約定。初始化完成后切到需求澄清技能/grill-me然后說(shuō)清楚你的目標(biāo)我要做一個(gè) todo 應(yīng)用先實(shí)現(xiàn)新增、完成、過(guò)濾三個(gè)能力。 請(qǐng)先問(wèn)我實(shí)現(xiàn)前必須確認(rèn)的問(wèn)題不要直接寫(xiě)代碼。這一步會(huì)逼著你把默認(rèn)沒(méi)想清楚的東西補(bǔ)上。比如數(shù)據(jù)要不要持久化、完成態(tài)怎么存、過(guò)濾支持哪些視圖、新增輸入要不要做空白處理、列表排序按什么規(guī)則、每條 todo 的唯一標(biāo)識(shí)怎么生成。這些問(wèn)題在寫(xiě)代碼之前問(wèn)清楚比寫(xiě)完再改省事得多。需求確認(rèn)完切到 TDD 技能/tdd引導(dǎo)它先寫(xiě)失敗測(cè)試先寫(xiě)一個(gè)失敗測(cè)試證明 todo 列表初始為空 再寫(xiě)一個(gè)測(cè)試證明用戶可以新增一個(gè)任務(wù) 最后再實(shí)現(xiàn)完成狀態(tài)和過(guò)濾邏輯。這樣做的好處是 AI 不會(huì)一開(kāi)始就把三個(gè)功能一起糊出來(lái)每一步都有測(cè)試兜底后面更容易逐步驗(yàn)證。如果測(cè)試沒(méi)過(guò)或者頁(yè)面行為和預(yù)期不一致切到診斷技能/diagnose讓它按「復(fù)現(xiàn) - 縮小 - 假設(shè) - 修復(fù)」的順序處理。常見(jiàn)的情況是狀態(tài)沒(méi)正確更新、過(guò)濾條件和渲染條件不一致、測(cè)試斷言寫(xiě)得太寬掩蓋了問(wèn)題。一個(gè)完整的最小對(duì)話順序就是/setup-matt-pocock-skills-/grill-me-/tdd-/diagnose。記住這個(gè)順序先問(wèn)清楚再寫(xiě)測(cè)試再寫(xiě)實(shí)現(xiàn)最后排查問(wèn)題。5. 常見(jiàn)報(bào)錯(cuò)排查401、local proxy failed、reading choices這一節(jié)對(duì)照真實(shí)報(bào)錯(cuò)來(lái)排查。我試過(guò)幾次配置寫(xiě)錯(cuò)的情況下面這幾個(gè)是最容易踩的。401 Unauthorized。這個(gè)最常見(jiàn)基本就是 Key 的問(wèn)題。檢查三件事Key 有沒(méi)有復(fù)制完整前后不能有空格、Key 有沒(méi)有過(guò)期、Key 有沒(méi)有填到正確的字段里。Claude Code 里是ANTHROPIC_AUTH_TOKENCodex 里是auth.json的OPENAI_API_KEY。如果 Key 是對(duì)的還報(bào) 401檢查 Base URL 是不是寫(xiě)成了https://taotoken.net/api/帶了尾部斜杠有些工具對(duì)尾部斜杠敏感去掉試試。local proxy failed / connection refused。這個(gè)報(bào)錯(cuò)說(shuō)明工具在嘗試連本地代理但連不上。檢查你的配置里有沒(méi)有殘留的http://localhost:xxxx或者h(yuǎn)ttp://127.0.0.1:xxxx地址。Claude Code 的settings.json和 Codex 的config.toml里Base URL 應(yīng)該直接指向https://taotoken.net/api不要經(jīng)過(guò)任何本地轉(zhuǎn)發(fā)。另外檢查環(huán)境變量里有沒(méi)有HTTP_PROXY或HTTPS_PROXY指向本地端口有的話清掉。reading choices / unexpected response format。這個(gè)報(bào)錯(cuò)通常是模型 ID 寫(xiě)錯(cuò)了或者 Base URL 指向了一個(gè)不兼容的接口。檢查ANTHROPIC_MODEL或model字段填的模型 ID 是否在 TaoToken 支持的列表里。Claude 系列用claude-sonnet-4-20250514這種格式GPT 系列用gpt-5-codex這種格式。模型 ID 寫(xiě)錯(cuò)的話接口返回的結(jié)構(gòu)對(duì)不上工具解析時(shí)就報(bào) reading choices 錯(cuò)誤。OAuth / authentication failed。Codex 有時(shí)候會(huì)走 OAuth 流程如果你用的是 API Key 模式檢查auth.json里是不是同時(shí)存在 OAuth token 和 API Key兩個(gè)同時(shí)存在會(huì)沖突。把 OAuth 相關(guān)的字段刪掉只留OPENAI_API_KEY。Claude Code 同理如果之前登錄過(guò)官方賬號(hào)settings.json里可能有殘留的 OAuth 配置清掉再試。技能不生效 / 命令找不到。SKILL.md 放對(duì)目錄了嗎Claude Code 是.claude/skills/技能名/SKILL.mdCodex 是.codex/skills/技能名/SKILL.md。frontmatter 里的name字段有沒(méi)有寫(xiě)name只能用字母數(shù)字連字符。改完配置重啟工具了嗎這三個(gè)都檢查一遍。模型不按技能流程走。有時(shí)候技能注冊(cè)成功了但模型還是自己發(fā)揮。檢查 SKILL.md 的description是不是寫(xiě)得太模糊。description 要寫(xiě)「什么時(shí)候用」比如「當(dāng)用戶要求實(shí)現(xiàn)新功能時(shí)使用」而不是「這是一個(gè) TDD 技能」。模型靠 description 做路由寫(xiě)清楚了它才會(huì)在合適的時(shí)機(jī)調(diào)用。6. 把 TaoToken 作為統(tǒng)一通道的長(zhǎng)期用法跑通第一個(gè)技能之后你可能會(huì)想把這套流程固定下來(lái)。這時(shí)候 TaoToken 的價(jià)值就體現(xiàn)出來(lái)了一個(gè) Key 管所有模型Claude Code、Codex、Cline 共用同一個(gè) Base URL不用每個(gè)工具單獨(dú)配一遍。長(zhǎng)期用的話建議把配置分成兩層。全局配置放~/.claude/settings.json和~/.codex/config.toml寫(xiě) TaoToken 的 Base URL 和 Key。項(xiàng)目級(jí)配置放.claude/skills/和.codex/skills/放具體的技能文件。這樣換項(xiàng)目的時(shí)候技能跟著項(xiàng)目走Key 不用重復(fù)填。模型 ID 可以按任務(wù)切換。需求澄清和架構(gòu)設(shè)計(jì)用 Claude 系列代碼生成和 TDD 用 GPT 系列在settings.json里改ANTHROPIC_MODEL就行。TaoToken 的模型對(duì)話頁(yè)面可以快速驗(yàn)證某個(gè)模型 ID 是否可用省得在工具里反復(fù)試。如果你要長(zhǎng)期跑編碼任務(wù)或者 Agent 流程Coding Plan 比按量計(jì)費(fèi)更劃算。接入文檔里有完整的配置示例覆蓋 Claude Code、Codex、Cline 等主流工具。API Keys 頁(yè)面管理你的 Key可以隨時(shí)生成新的或吊銷舊的。技能文件本身也可以版本化。把.claude/skills/和.codex/skills/提交到 git團(tuán)隊(duì)里每個(gè)人拉下來(lái)就能用同一套工作流。mattpocock/skills 倉(cāng)庫(kù)里的技能可以直接復(fù)制進(jìn)項(xiàng)目也可以按自己團(tuán)隊(duì)的規(guī)范改 SKILL.md 的正文部分。改的時(shí)候注意別動(dòng) frontmatter 的name那個(gè)是調(diào)用入口。最后說(shuō)一個(gè)實(shí)際經(jīng)驗(yàn)技能不是越多越好。裝太多技能會(huì)讓模型在路由時(shí)猶豫反而降低效率。建議保持 3 到 5 個(gè)核心技能覆蓋需求澄清、TDD、診斷這三個(gè)環(huán)節(jié)就夠了。其他的按需臨時(shí)裝用完可以刪。