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