1. 從一次“工具調(diào)用失敗”說起Skill 機制到底解決什么問題如果你最近在折騰 Agent 工具鏈大概率遇到過這種場景模型明明“知道”該調(diào)用哪個工具但一到具體執(zhí)行就翻車——要么參數(shù)格式不對要么根本不知道某個庫該怎么用。我試過把 PDF 處理、圖片壓縮、音視頻轉碼這些能力全塞進 system prompt結果上下文直接爆掉模型反而變笨了。這就是 Skill 機制要解決的核心問題。Skill 是什么一句話概括Skill 知識文檔SKILL.md 加載器skill_loader.py 底層 Tool 執(zhí)行能力。它不是一門新技術而是把“按需加載領域知識”這件事工程化了。能做什么讓模型在需要處理 PDF 時才加載 PDF 的處理指南需要操作數(shù)據(jù)庫時才加載 SQL 規(guī)范平時這些知識不占用上下文。適合誰正在把自建能力接入多模型工具鏈的開發(fā)者尤其是那些已經(jīng)有一堆 Tool 和 MCP Server、但發(fā)現(xiàn) token 消耗失控的團隊。傳統(tǒng)做法是把所有工具定義和領域知識一次性注入。MCP 官方博客里提到過兩個典型問題工具定義會讓上下文窗口過載中間工具的結果會消耗額外 token。Skill 的思路是“漸進式加載”——SKILL.md 平時躺在磁盤上只有觸發(fā)條件匹配時才被讀進上下文。整條鏈路是這樣的用戶提問 → 關鍵詞匹配到某個 Skill → skill_loader.py 解析 SKILL.md → 把正文注入 system prompt → 模型根據(jù)知識決定是否調(diào)用 Tool → ToolExecutor 執(zhí)行 → 結果返回模型。注意中間那步“決定是否調(diào)用 Tool”是可選的如果用戶只是問“PDF 提取表格有幾種方法”模型靠 SKILL.md 的知識就能回答不需要真的執(zhí)行代碼。理解了這條鏈路你就能明白為什么 Skill 和 Tool、MCP 是互補而非替代關系。Tool 給模型“手”MCP 給模型“遠程手”Skill 給模型“大腦的參考資料”。下面我會從 SKILL.md 的最小模板開始一步步拆到 skill_loader.py 的解析邏輯最后用 TaoToken 統(tǒng)一 Key 驗證整條 Tool 與 MCP 調(diào)用鏈是否連通。2. SKILL.md 最小模板與 skill_loader.py 解析邏輯從聲明到注冊為 Tool2.1 SKILL.md 的兩段式結構每個 Skill 就是一個 Markdown 文件結構分兩部分YAML 元數(shù)據(jù) 正文知識。元數(shù)據(jù)用---包裹至少包含name和description兩個字段。description的寫法很關鍵它決定了模型什么時候該激活這個 Skill。下面是一個可以直接復制使用的最小模板我把它放在skills/pdf/SKILL.md--- name: pdf description: Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill. license: Proprietary. LICENSE.txt has complete terms --- # PDF Processing Guide ## Overview 處理 PDF 時優(yōu)先使用 pdfplumber 提取文本和表格它比 PyPDF2 對復雜版式更友好。 ## Extract Tables python import pdfplumber with pdfplumber.open(input.pdf) as pdf: page pdf.pages[0] tables page.extract_tables() for table in tables: for row in table: print(row)Merge PDFs使用 pypdf 的 PdfMergerfrom pypdf import PdfMerger merger PdfMerger() merger.append(a.pdf) merger.append(b.pdf) merger.write(merged.pdf) merger.close()元數(shù)據(jù)里的 description 寫得越具體觸發(fā)匹配越準。我見過有人只寫“處理 PDF”結果模型在用戶提到“文檔”時就誤激活。把具體動作extract、merge、split、OCR都列出來匹配精度會高很多。 ### 2.2 skill_loader.py 的 23 行核心邏輯 加載器的職責很單一讀文件、切分元數(shù)據(jù)和正文、返回結構化結果。核心就是判斷文件是否以 --- 開頭然后用 split(---, 2) 切成三部分。下面是完整實現(xiàn) python Skill 加載模塊 import yaml def load(path: str) - tuple[dict, str]: 解析 SKILL.md 文件返回 (metadata, content)。 with open(path, r, encodingutf-8) as f: content f.read() if not content.startswith(---): return {}, content # 只分割成三部分前導空字符串、metadata、剩余內(nèi)容 parts content.split(---, 2) if len(parts) 3: return {}, content metadata yaml.safe_load(parts[1]) body parts[2].strip() return metadata or {}, body if __name__ __main__: import sys from pathlib import Path script_dir Path(__file__).parent test_file script_dir / skills/pdf/SKILL.md if len(sys.argv) 1: test_file Path(sys.argv[1]) print(fLoading: {test_file}) print( * 50) meta, body load(str(test_file)) print(METADATA:) for k, v in meta.items(): display f{v[:60]}... if isinstance(v, str) and len(v) 60 else v print(f {k}: {display}) print(f\nCONTENT (first 300 chars):\n{body[:300]}...)這里有個容易踩的坑split(---, 2)的第二個參數(shù)是最大分割次數(shù)不是分割份數(shù)。如果寫成split(---)正文里出現(xiàn)的---分隔線會把內(nèi)容切碎。用maxsplit2才能保證只切出元數(shù)據(jù)部分。2.3 從解析結果到注冊為 Tool加載器返回的metadata用來做觸發(fā)判斷body才是注入上下文的知識。但 Skill 本身不包含執(zhí)行邏輯它只是“告訴模型怎么做”。真正執(zhí)行時模型還是要通過 ToolExecutor 調(diào)用內(nèi)置工具。注冊流程可以這樣理解啟動時掃描skills/目錄下所有SKILL.md把metadata.name和metadata.description注冊成一個輕量級的“可激活 Skill 列表”。這個列表本身很小不占多少 token。當用戶輸入進來先用關鍵詞或向量匹配判斷該激活哪個 Skill再調(diào)用load()把對應正文讀進來。如果你用的是支持 MCP 的客戶端可以把 Skill 加載器包裝成一個 MCP Server 暴露出去。這樣模型既能通過 MCP 調(diào)用遠程服務又能通過 Skill 獲取領域知識兩條鏈路共用同一套 Key 管理。3. 可復制配置用 TaoToken 統(tǒng)一 Key 打通 Tool 與 MCP 調(diào)用鏈3.1 為什么需要統(tǒng)一 Key當你的 Agent 同時要調(diào)用多個模型、多個 MCP Server、多個自建 Tool 時Key 管理會變成噩夢。每個服務一套 Key輪換時到處改配置還容易把 Key 硬編碼進代碼提交到倉庫。TaoToken 的做法是提供一個統(tǒng)一的 API 入口Base URL 指向https://taotoken.net/api所有模型調(diào)用和工具調(diào)用都走這一個 Key。這樣配置的好處是skill_loader.py 里不需要關心具體用哪個模型只需要在調(diào)用時指定 Model IDMCP Server 的連接配置也統(tǒng)一走同一個 Base URL。換模型時只改一個字段不用動加載器邏輯。3.2 settings.json 配置片段如果你用的是 Claude Code 或類似的客戶端配置文件通常放在~/.claude/settings.json。下面是一個可復制的配置片段把 Base URL、Key、Model ID 三件套都寫全{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-your-taotoken-key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, skills: { enabled: true, paths: [./skills] }, mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./workspace] } } }注意ANTHROPIC_BASE_URL后面不要加/v1TaoToken 的 API 入口已經(jīng)處理了路徑。Key 從控制臺的 API Keys 頁面獲取不要直接寫死在代碼里用環(huán)境變量注入更安全。3.3 skill_loader.py 與 MCP 的橋接配置如果你想讓 Skill 加載器本身也通過 MCP 暴露可以在 MCP Server 配置里加一個自定義 Server。下面是一個 TOML 格式的配置示例適用于支持 TOML 配置的客戶端[mcp_servers.skill_loader] command python args [-m, skill_loader_server, --skills-dir, ./skills] [mcp_servers.skill_loader.env] TAOTOKEN_BASE_URL https://taotoken.net/api TAOTOKEN_API_KEY sk-your-taotoken-key TAOTOKEN_MODEL claude-sonnet-4-20250514這樣配置后模型可以通過 MCP 協(xié)議調(diào)用skill_loader的list_skills和load_skill兩個方法動態(tài)獲取可用 Skill 列表和具體內(nèi)容。整個鏈路里Tool 調(diào)用、MCP 調(diào)用、Skill 加載都共用同一個 TaoToken Key。3.4 驗證配置是否生效配置寫完后先用一個最小請求驗證 Key 和 Base URL 是否連通?？梢杂?curl 直接測curl -X POST https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-your-taotoken-key \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 100, messages: [{role: user, content: 回復 OK 兩個字母}] }如果返回里包含content字段且文本是OK說明 Key 和 Base URL 都正確。這一步過了再往下測 Skill 加載和 MCP 調(diào)用。4. 驗證請求與成功結果實測 Skill 加載與 MCP 調(diào)用是否連通4.1 單獨測試 skill_loader.py先不接模型直接跑加載器確認 SKILL.md 能被正確解析python skill_loader.py skills/pdf/SKILL.md預期輸出類似Loading: skills/pdf/SKILL.md METADATA: name: pdf description: Use this skill whenever the user wants to do anything with PDF files... license: Proprietary. LICENSE.txt has complete terms CONTENT (first 300 chars): # PDF Processing Guide ## Overview 處理 PDF 時優(yōu)先使用 pdfplumber 提取文本和表格...如果METADATA是空的檢查文件開頭是不是有 BOM 或者空格。content.startswith(---)對首字符很敏感Windows 下用記事本保存容易帶 BOM用 VS Code 另存為 UTF-8 無 BOM 即可。4.2 測試模型能否根據(jù) Skill 知識調(diào)用 Tool寫一個最小測試腳本把 SKILL.md 的正文注入 system prompt然后讓模型處理一個 PDF 任務import anthropic client anthropic.Anthropic( base_urlhttps://taotoken.net/api, api_keysk-your-taotoken-key, ) with open(skills/pdf/SKILL.md, r, encodingutf-8) as f: content f.read() parts content.split(---, 2) body parts[2].strip() response client.messages.create( modelclaude-sonnet-4-20250514, max_tokens500, systemf你是 PDF 處理專家參考以下指南\n\n{body}, messages[{role: user, content: 幫我寫一段提取 PDF 表格的代碼}], ) print(response.content[0].text)成功的話模型會輸出使用pdfplumber的代碼而不是泛泛而談。這說明 Skill 知識已經(jīng)正確注入模型能根據(jù)知識決定調(diào)用哪個 Tool。4.3 測試 MCP 調(diào)用鏈如果你配置了 MCP Server可以用客戶端自帶的 MCP 調(diào)試命令驗證。以 filesystem Server 為例npx modelcontextprotocol/inspector npx -y modelcontextprotocol/server-filesystem ./workspace在 Inspector 界面里能看到list_directory、read_file等工具。點擊調(diào)用如果返回文件列表說明 MCP 鏈路通了。這時候再回到模型側讓模型通過 MCP 讀取一個文件觀察返回結果里是否包含文件內(nèi)容。4.4 完整鏈路成功標志整條鏈路跑通的標志是用戶提問 → 模型匹配到 pdf Skill → 加載 SKILL.md → 模型決定調(diào)用 bash Tool 執(zhí)行pip install pdfplumber→ ToolExecutor 返回安裝結果 → 模型輸出最終代碼。整個過程里模型調(diào)用走 TaoToken 的 Base URLMCP 調(diào)用走同一個 KeySkill 加載走本地文件系統(tǒng)。三者互不干擾但共用一套認證。5. 本篇常見錯誤排查401、local proxy failed、reading choices、OAuth5.1 401 Unauthorized最常見的報錯。原因通常是 Key 寫錯、Key 過期、或者 Base URL 配錯。先檢查ANTHROPIC_AUTH_TOKEN是不是從控制臺復制的完整 Key注意不要有多余空格。然后確認ANTHROPIC_BASE_URL是https://taotoken.net/api不要寫成https://taotoken.net/api/v1路徑重復會導致 404 或 401。如果用的是 settings.json檢查 JSON 格式是否合法?？梢杂胮ython -m json.tool settings.json驗證。JSON 里不能有注釋尾逗號也會導致解析失敗。5.2 local proxy failed這個報錯通常出現(xiàn)在客戶端嘗試連接本地代理時。檢查你的環(huán)境變量里有沒有HTTP_PROXY或HTTPS_PROXY指向一個不存在的本地端口。如果有臨時取消這些環(huán)境變量再試unset HTTP_PROXY unset HTTPS_PROXY另外檢查 settings.json 里有沒有配置proxy字段指向本地地址。TaoToken 的 API 入口是直連的不需要額外代理配置。5.3 reading choices 相關報錯這個報錯一般出現(xiàn)在解析模型返回結果時。如果返回體里沒有choices字段說明請求可能發(fā)到了錯誤的端點。檢查你用的 SDK 是不是 Anthropic 格式Anthropic 的返回是content數(shù)組不是choices。如果你用的是 OpenAI 格式的 SDK需要把 Base URL 改成對應的兼容端點或者換用 Anthropic SDK。還有一種情況是流式返回被中斷導致 JSON 解析失敗?？梢栽谡埱罄锛觭tream: false先排除流式問題。5.4 OAuth 相關報錯如果你在客戶端里配置了 OAuth 登錄但同時又配了 API Key兩者可能沖突。OAuth 流程會嘗試刷新 token如果刷新失敗就會報錯。解決辦法是明確用哪一種認證方式用 API Key 就把 OAuth 相關配置清掉用 OAuth 就不要在環(huán)境變量里放ANTHROPIC_AUTH_TOKEN。5.5 Skill 加載后模型不調(diào)用 Tool這不是報錯但很常見。模型讀完 SKILL.md 后只是回答了問題沒有調(diào)用 Tool。原因可能是description寫得太模糊模型沒匹配到或者 system prompt 里沒有明確告訴模型“你可以調(diào)用工具”?？梢栽?system prompt 里加一句“如果需要執(zhí)行代碼請調(diào)用 bash 工具”給模型一個明確的行動指令。6. 把 Skill 接入你的工具鏈從驗證到長期使用整條鏈路驗證通過后你可以把 skill_loader.py 包裝成一個常駐服務啟動時掃描skills/目錄把每個 SKILL.md 的元數(shù)據(jù)注冊到內(nèi)存里。用戶輸入進來時先用輕量級匹配關鍵詞或向量判斷該激活哪個 Skill再調(diào)用load()讀取正文。這樣既節(jié)省 token又保證模型在需要時能拿到準確的領域知識。長期使用時建議把 Skill 目錄納入版本管理每個 Skill 一個文件夾SKILL.md 里的description當成接口文檔來維護。新增 Skill 時先寫 SKILL.md再用skill_loader.py單獨測試解析最后接入模型驗證觸發(fā)是否準確。如果你需要管理多個模型和多個 MCP Server用 TaoToken 的統(tǒng)一 Key 能省掉大量配置工作。模型對話可以在控制臺里直接測試API Keys 頁面管理所有 Key接入文檔里有各客戶端的詳細配置示例。需要長期跑編碼任務或 Agent 的話Coding Plan 提供了更穩(wěn)定的配額。整條 Tool 與 MCP 調(diào)用鏈的連通性用上面那套 curl 加 Python 腳本就能驗證不需要復雜的測試框架。