：從零開發(fā)可復(fù)用技能，理清與 MCP、Tool 的區(qū)別)
從 2025 年初開始“Agent Skill”這個詞在 AI 大模型開發(fā)圈子里的出現(xiàn)頻率越來越高。但打開網(wǎng)上的教程你會發(fā)現(xiàn)一個很尷尬的現(xiàn)象講 Agent 概念的文章鋪天蓋地一旦深入到 Skill 怎么設(shè)計、怎么寫、怎么調(diào)試內(nèi)容就斷崖式減少。更讓人頭疼的是Skill、Agent、Tool、MCP 這四個概念經(jīng)常被混在一起講讀完反而更迷糊。這篇文章不想復(fù)述概念而是想解決三個具體問題第一把 Skill 和 Agent、Tool、MCP 的關(guān)系徹底講清楚尤其是“Skill 和 MCP 有什么區(qū)別”這個高頻疑問第二用一套最小但完整的 Python 代碼演示如何從零開發(fā)一個 Skill并讓 Agent 在對話中自動選擇和使用它第三把開發(fā)過程中真正容易踩的坑和工程化建議整理成清單方便你直接用到項目里。核心判斷先放在前面Skill 不是 Agent 的另一個名字也不是 MCP 的替代品。Skill 解決的是“能力封裝與復(fù)用”的問題MCP 解決的是“能力接入與互通”的問題Agent 才是那個負責“決策與調(diào)度”的主體。理解了這個分層你再看任何 Agent 框架都會順暢很多。1. 這篇文章真正要解決的問題先說說為什么 Agent Skill 值得單獨寫一篇長文。很多人已經(jīng)會調(diào)用大模型 API寫一個聊天程序并不難把用戶問題拼進 Prompt調(diào)用 Chat Completion 接口拿到結(jié)果返回給前端。這算 AI 應(yīng)用但還稱不上 Agent 應(yīng)用。Agent 和普通聊天的本質(zhì)區(qū)別在于 Agent 有自主規(guī)劃、工具調(diào)用和任務(wù)執(zhí)行的能力。而 Skill 就是“工具調(diào)用能力”的一種高級封裝形態(tài)。如果你只會在代碼里寫死調(diào)用某一個函數(shù)那 Agent 的“自主性”是不存在的只有把能力抽象成 Skill讓模型根據(jù)用戶意圖去匹配和調(diào)用Agent 才算真正“活”起來。從行業(yè)趨勢看AI 大模型應(yīng)用開發(fā)正在經(jīng)歷一個明顯的轉(zhuǎn)折基礎(chǔ)模型的能力差距在縮小真正拉開產(chǎn)品體驗差距的是模型外圍的工程能力——知識庫怎么組織、工具怎么接入、技能怎么沉淀、流程怎么編排。Skill 恰好是這條鏈路里承上啟下的關(guān)鍵一環(huán)。所以這篇文章的讀者畫像很明確已經(jīng)會調(diào)用大模型 API但想進一步做 Agent 應(yīng)用開發(fā)的開發(fā)者用過 Dify、FastGPT、Coze 等平臺但不滿足于拖拽配置想理解底層運行機制的人團隊里需要多人協(xié)作開發(fā) Agent 功能想統(tǒng)一管理“能力塊”的技術(shù)負責人正在糾結(jié) MCP 和 Skill 怎么選不知道它們適用邊界的初學者。如果你屬于其中任何一類這篇文章會給你一條從概念到落地的完整路徑。我們會先建立認知框架再寫代碼再講排錯最后給工程化建議。2. Agent Skill 核心概念它到底是什么2.1 從 Tool 到 Skill 的演進邏輯要理解 Skill得先理解它從哪來。在最早的 Agent 實現(xiàn)里開發(fā)者會把“工具”以函數(shù)形式注冊給模型。比如一個天氣查詢函數(shù)get_weather(city: string) - string模型在對話中檢測到用戶想查天氣就生成一個函數(shù)調(diào)用請求由代碼執(zhí)行后把結(jié)果返回給模型。這是 Function Calling 的標準流程也是現(xiàn)在所有 Agent 框架的底座。這種方式在小規(guī)模場景下沒有問題但一旦工具多起來問題就出現(xiàn)了每個工具都只是“一個函數(shù)”缺少使用說明和邊界描述模型經(jīng)常用錯一個完整任務(wù)往往需要多個函數(shù)配合比如“先查天氣再根據(jù)天氣推薦穿搭”這種組合邏輯沒有地方放工具的 Prompt 說明散落在系統(tǒng)提示詞里維護成本越來越高。Skill 的出現(xiàn)就是為了解決這些問題。它把“一組相關(guān)的指令、說明、代碼和資源”打包成一個獨立的、可復(fù)用的單元。你可以把 Skill 理解成一個自帶說明書的能力模塊模型看到 Skill 的描述后知道什么時候該用它、怎么用、有哪些注意事項。用生活場景類比Tool 是工具箱里的一把螺絲刀Skill 是一本“如何拆裝一臺電腦”的圖文教程里面既有工具清單也有操作步驟還有常見問題的處理方法。Agent 拿到任務(wù)后不是自己去翻工具箱而是先看教程再按教程里的指引執(zhí)行。2.2 Skill 與 Agent 的區(qū)別這是很多人最容易混淆的一組概念。Agent 是決策主體它負責接收任務(wù)、拆解計劃、調(diào)用能力、判斷結(jié)果是否達標、決定下一步動作。Agent 是一個“運行中的智能體”它有狀態(tài)、有上下文、有循環(huán)邏輯。Skill 是能力單元它是被 Agent 調(diào)用的“技能包”。Skill 本身沒有決策能力它只負責把一件事做好。比如“把 Markdown 轉(zhuǎn)成 PDF”“調(diào)用數(shù)據(jù)庫查詢用戶訂單”“對一段文本做情感分析”這些都可以是獨立的 Skill。打個比方Agent 是一個廚師Skill 是廚師掌握的做菜技能。廚師Agent決定今天做什么菜、先做哪道、火候怎么控制技能Skill負責具體的操作流程比如“紅燒肉怎么做”“清蒸魚怎么處理”。技能本身不會想問題但它知道怎么把事情執(zhí)行到位。在實際代碼里這種區(qū)別體現(xiàn)為Agent 是一個循環(huán)loop里面有規(guī)劃、調(diào)用、觀察、反思Skill 是一組注冊好的能力描述和實現(xiàn)函數(shù)Agent 在循環(huán)里根據(jù)用戶需求去匹配它們。2.3 Skill 與 MCP 的區(qū)別“agent skill 和 mcp有什么區(qū)別”是近期的熱門搜索詞說明很多人在這兩個概念上卡住了。簡單直接地說MCPModel Context Protocol是一種標準協(xié)議它解決的是“模型怎么連接到外部工具和數(shù)據(jù)源”的問題。你可以把它理解為 USB-C 接口標準——不管是什么設(shè)備只要遵守這個接口規(guī)范就能互相連接。MCP Server 負責把工具暴露給客戶端MCP Client 負責跟 Server 通信。Skill 是一種能力封裝它解決的是“這個能力怎么被正確地使用”的問題。Skill 里可以包含提示詞、使用說明、示例、代碼邏輯甚至也可以是 MCP Server 的配置。兩者不是競爭關(guān)系而是不同層次的東西。一個 Skill 內(nèi)部完全可以依賴 MCP 去調(diào)用遠程工具。MCP 管“連接”Skill 管“封裝”。用表格對比更清晰對比維度Agent SkillMCP本質(zhì)能力封裝單元標準化連接協(xié)議解決問題如何讓模型正確使用復(fù)雜能力如何讓模型接入外部工具和數(shù)據(jù)主要內(nèi)容提示詞、說明、代碼、資源工具定義、傳輸協(xié)議、服務(wù)端/客戶端能否獨立運行需要被 Agent 加載后調(diào)用服務(wù)端可獨立運行客戶端負責接入典型場景把領(lǐng)域知識工具邏輯打包成技能統(tǒng)一的工具接入網(wǎng)關(guān)結(jié)論很明確做 Agent 應(yīng)用時Skill 和 MCP 不是二選一而是協(xié)同使用。先用 MCP 把工具接進來再用 Skill 告訴模型怎么用好這些工具。2.4 Skill 與 Plugin、Workflow 的關(guān)系還有一個容易混淆的點是 Skill、Plugin、Workflow 的邊界。Plugin 更偏向“應(yīng)用擴展”通常包含完整的用戶界面和交互邏輯比如瀏覽器插件、IDE 插件。在 Agent 語境下Plugin 往往被用作“可插拔功能包”的統(tǒng)稱Skill 可以理解為 Plugin 的一種更聚焦、更面向模型的設(shè)計形態(tài)。Workflow 則是“固定流程編排”它強調(diào)步驟和順序比如“先查庫存再下訂單最后發(fā)通知”。Workflow 通常是確定性的每一步做什么是預(yù)先定義好的。Skill 則更靈活它更像一個“可以被模型按需調(diào)用的能力包”模型會根據(jù)當前上下文決定是否使用、如何使用。一句話總結(jié)Workflow 是寫好的劇本Skill 是演員掌握的技能。劇本規(guī)定了每一幕怎么演技能讓演員在即興發(fā)揮時也能不砸場。3. 為什么需要 Agent Skill工程化視角的三個理由3.1 提示詞膨脹問題做 Agent 應(yīng)用的人遲早會遇到這個問題系統(tǒng)提示詞越寫越長。一開始只有角色設(shè)定后來加上工具說明再后來加上各種注意事項、格式要求、示例最后 Prompt 達到幾千 token每次請求的延遲和成本都在漲。Skill 提供了一種拆分思路把不同能力的說明從系統(tǒng)提示詞中拆出去只在 Agent 需要時按需加載描述真正執(zhí)行時才把完整內(nèi)容注入上下文。這樣系統(tǒng)提示詞保持精簡模型每次只需要關(guān)注當前任務(wù)相關(guān)的 Skill 內(nèi)容既省錢又更精準。從這里能看出 Skill 的另一個價值它讓“上下文管理”從黑盒變成了結(jié)構(gòu)化操作。哪些 Skill 被加載了、加載了哪些內(nèi)容、占了多少 token都是可統(tǒng)計、可優(yōu)化的。3.2 能力復(fù)用與團隊協(xié)作在一個團隊里不同業(yè)務(wù)線可能需要相似的能力。比如“文本總結(jié)”這個能力客服機器人要用內(nèi)容審核要用數(shù)據(jù)分析助手也要用。如果沒有 Skill 機制每個項目各寫各的 Prompt 和調(diào)用邏輯很快就會出現(xiàn)三種效果不一致的實現(xiàn)還互相不知道。Skill 把能力沉淀成一個獨立模塊后團隊可以像管理代碼庫一樣管理技能庫。新增一個業(yè)務(wù)場景時先查一下技能庫有沒有現(xiàn)成的 Skill有就直接引用沒有就開發(fā)一個并提交入庫。這種模式大大降低了重復(fù)開發(fā)成本。3.3 讓 Agent 的“技能”可測試、可回滾這是 Skill 最容易被忽視的工程價值。如果你把能力邏輯寫死在 Agent 主流程里想測一個新方案只能改主流程代碼影響面大、回歸成本高。但 Skill 是獨立單元你可以單獨給它構(gòu)造輸入輸出做單元測試可以在生產(chǎn)和測試環(huán)境加載不同版本的 Skill出問題后可以快速回滾到上一個版本而不影響 Agent 主體。這就把 Agent 開發(fā)從“調(diào) Prompt 玄學”推向更接近傳統(tǒng)軟件工程的狀態(tài)模塊化、可測試、可版本化。4. 環(huán)境準備與前置條件4.1 技術(shù)棧選擇本文的示例代碼使用 Python 3這是目前 AI 大模型應(yīng)用開發(fā)最主流的語言相關(guān)生態(tài)最成熟。版本方面以實際項目為準建議 Python 3.10 以上本文代碼沒有依賴任何特定框架只使用標準庫和 requests 庫方便你理解底層原理。如果你平時用 Java、Node.js文章后面的設(shè)計思路同樣適用只是代碼示例需要用對應(yīng)語言改寫。4.2 大模型 API 準備示例中的“文本總結(jié) Skill”需要調(diào)用大模型 API。你可以選擇任意兼容 OpenAI 接口格式的服務(wù)包括國內(nèi)主流大模型廠商的 API或者本地部署的模型服務(wù)。關(guān)鍵點只有一個API 地址和密鑰通過環(huán)境變量配置不要寫死在代碼里。本文為了聚焦知識點統(tǒng)一使用 OpenAI 風格的接口調(diào)用方式。你只需要替換 base_url 和 api_key 即可。如果本地部署了模型也可以把 base_url 指向本地服務(wù)。4.3 項目目錄結(jié)構(gòu)我們用一個最小但完整的目錄來承載示例agent-skill-demo/ ├── requirements.txt ├── skills/ │ ├── json_formatter/ │ │ ├── SKILL.md │ │ └── skill.py │ └── text_summarizer/ │ ├── SKILL.md │ └── skill.py ├── agent.py └── skill_loader.py這個結(jié)構(gòu)體現(xiàn)的是 Skill 的核心設(shè)計思想每個 Skill 一個目錄目錄內(nèi)包含說明文件SKILL.md和實現(xiàn)代碼skill.py。Agent 運行前通過 loader 掃描 skills 目錄解析每個 SKILL.md把技能描述注冊給模型當模型決定調(diào)用某個 Skill 時loader 再執(zhí)行對應(yīng)的 skill.py。5. 核心流程拆解從零開發(fā)一個 Skill 的完整過程開發(fā)一個 Skill 通常分四步定義邊界、編寫描述、實現(xiàn)邏輯、注冊加載。每一步都有設(shè)計問題需要注意。5.1 第一步定義 Skill 的邊界這是最容易被忽略卻最重要的一步。一個 Skill 應(yīng)該只做一件事并且邊界清晰。不好的例子做一個“數(shù)據(jù)處理 Skill”里面既做 JSON 格式化又做文本總結(jié)還做數(shù)據(jù)可視化。這個 Skill 的描述沒法寫清楚模型也不知道什么時候該用它。好的例子把“JSON 格式化”單獨做成一個 Skill描述里寫清楚“當用戶提供一段 JSON 字符串并希望進行格式化、校驗或壓縮時使用此 Skill”。邊界清晰模型才能準確匹配。定義邊界的判斷標準很簡單你能否用一句話說清楚這個 Skill 在什么條件下被觸發(fā)如果說不清楚說明邊界有問題。5.2 第二步編寫技能描述文件Skill 的描述文件是整個機制的“說明書”。它的質(zhì)量直接決定模型能不能正確使用這個 Skill。一份好的描述文件至少包含以下內(nèi)容技能名稱簡短、準確觸發(fā)條件什么情況下模型應(yīng)該使用這個技能使用說明如何調(diào)用輸入?yún)?shù)是什么輸出是什么注意事項什么情況下不要使用有什么限制示例給一個輸入輸出示例幫助模型理解。記住一個原則描述文件是寫給模型看的不是寫給開發(fā)者看的。你是在教一個聰明但沒有經(jīng)驗的實習生怎么使用工具而不是在寫給自己看的代碼注釋。5.3 第三步實現(xiàn)執(zhí)行邏輯Skill 的執(zhí)行邏輯就是普通 Python 函數(shù)接收輸入返回結(jié)果。關(guān)鍵設(shè)計點是輸入輸出要結(jié)構(gòu)化方便 Agent 主循環(huán)解析。推薦統(tǒng)一采用字典結(jié)構(gòu)至少包含 status、result 兩個字段方便判斷成功或失敗。5.4 第四步注冊與加載Agent 啟動時會掃描 skills 目錄讀取所有 SKILL.md把其中的描述信息轉(zhuǎn)換成模型可識別的工具定義格式OpenAI 風格的 functions 或 tools。這一步相當于把“技能說明書”裝進模型的工具列表里。模型在對話中看到這些技能描述后會根據(jù)用戶意圖生成調(diào)用請求Agent 執(zhí)行對應(yīng)函數(shù)再把結(jié)果返回給模型繼續(xù)推理。6. 完整示例代碼實戰(zhàn)6.1 示例一JSON 格式化 Skill先實現(xiàn)一個最簡單但完整的 Skill。文件路徑skills/json_formatter/SKILL.md# JSON Formatter ## 觸發(fā)條件 當用戶要求對 JSON 字符串進行格式化、壓縮、校驗或解析時使用。 ## 使用說明 輸入?yún)?shù) - action: 必填取值 format格式化或 compress壓縮 - json_str: 必填待處理的 JSON 字符串 輸出 - 格式化或壓縮后的 JSON 字符串 - 如果 JSON 解析失敗返回錯誤信息 ## 注意事項 不要在用戶沒有明確要求 JSON 處理時使用此技能。文件路徑skills/json_formatter/skill.pyimport json def run(params: dict) - dict: action params.get(action) json_str params.get(json_str, ) if not action or not json_str: return {status: error, result: 缺少 action 或 json_str 參數(shù)} try: data json.loads(json_str) except json.JSONDecodeError as e: return {status: error, result: fJSON 解析失敗: {e}} if action format: result json.dumps(data, ensure_asciiFalse, indent2) elif action compress: result json.dumps(data, ensure_asciiFalse, separators(,, :)) else: return {status: error, result: f不支持的 action: {action}} return {status: success, result: result}這段代碼的邏輯很簡單先解析 JSON 驗證合法性再根據(jù) action 決定是格式化還是壓縮。注意這里的返回結(jié)構(gòu)是統(tǒng)一的字典格式Agent 主循環(huán)拿到 status 為 success 或 error 后可以決定把結(jié)果交給模型還是觸發(fā)錯誤處理。6.2 示例二調(diào)用大模型的文本總結(jié) Skill第二個示例演示 Skill 內(nèi)部如何調(diào)用大模型這是實際開發(fā)中最常見的形態(tài)。文件路徑skills/text_summarizer/SKILL.md# Text Summarizer ## 觸發(fā)條件 當用戶要求對一段較長的文本進行摘要、總結(jié)、提煉要點時使用。 ## 使用說明 輸入?yún)?shù) - text: 必填需要總結(jié)的文本內(nèi)容 - max_length: 可選總結(jié)的最大字數(shù)默認 200 輸出 - 對原文的總結(jié)內(nèi)容 ## 注意事項 - 文本過長時優(yōu)先截取核心部分再調(diào)用模型 - 不要對代碼、JSON 等結(jié)構(gòu)化內(nèi)容使用此技能文件路徑skills/text_summarizer/skill.pyimport os import requests def run(params: dict) - dict: text params.get(text, ) max_length params.get(max_length, 200) if not text: return {status: error, result: 缺少 text 參數(shù)} api_key os.getenv(LLM_API_KEY) base_url os.getenv(LLM_BASE_URL, https://api.openai.com/v1) model os.getenv(LLM_MODEL, gpt-4o-mini) prompt f請對下面的文本進行總結(jié)不超過 {max_length} 字\n\n{text} try: resp requests.post( f{base_url}/chat/completions, headers{Authorization: fBearer {api_key}}, json{ model: model, messages: [{role: user, content: prompt}], temperature: 0.3, }, timeout60, ) resp.raise_for_status() summary resp.json()[choices][0][message][content] return {status: success, result: summary} except Exception as e: return {status: error, result: f調(diào)用模型失敗: {e}}這個 Skill 演示了一個關(guān)鍵設(shè)計Skill 內(nèi)部也可以調(diào)用模型但 Skill 本身不負責“決定做什么”只負責“把總結(jié)這件事做好”。模型 API 地址、密鑰、模型名全部通過環(huán)境變量讀取這是生產(chǎn)環(huán)境的最低要求。6.3 示例三Skill 加載器與 Agent 主循環(huán)前面兩個 Skill 是獨立的現(xiàn)在需要把它們接入 Agent。先寫一個加載器。文件路徑skill_loader.pyimport importlib.util import os from pathlib import Path SKILLS_DIR Path(__file__).parent / skills def _read_skill_md(skill_dir: Path) - str: md_path skill_dir / SKILL.md if not md_path.exists(): return return md_path.read_text(encodingutf-8) def load_skills(): skills [] if not SKILLS_DIR.exists(): return skills for skill_dir in SKILLS_DIR.iterdir(): if not skill_dir.is_dir(): continue description _read_skill_md(skill_dir) if not description: continue # 將 SKILL.md 轉(zhuǎn)成模型工具描述 tool_def { type: function, function: { name: skill_dir.name, description: description[:1024], parameters: { type: object, properties: { action: {type: string}, json_str: {type: string}, text: {type: string}, max_length: {type: integer}, } }, }, } skills.append({name: skill_dir.name, tool_def: tool_def, path: skill_dir}) return skills def execute_skill(skill_name: str, params: dict) - dict: skill_dir SKILLS_DIR / skill_name py_path skill_dir / skill.py if not py_path.exists(): return {status: error, result: fSkill {skill_name} 不存在} spec importlib.util.spec_from_file_location(skill_name, py_path) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) return module.run(params)這里為了方便演示把參數(shù) schema 寫死成了所有 Skill 的并集。實際項目中推薦讓每個 SKILL.md 里的 YAML front-matter 聲明自己的參數(shù) schemaloader 動態(tài)解析這里不做過度展開。接著寫 Agent 主循環(huán)。文件路徑agent.pyimport json import os import requests from skill_loader import load_skills, execute_skill def call_llm(messages, tools): api_key os.getenv(LLM_API_KEY) base_url os.getenv(LLM_BASE_URL, https://api.openai.com/v1) model os.getenv(LLM_MODEL, gpt-4o-mini) payload { model: model, messages: messages, tools: tools, tool_choice: auto, temperature: 0.3, } resp requests.post( f{base_url}/chat/completions, headers{Authorization: fBearer {api_key}}, jsonpayload, timeout120, ) resp.raise_for_status() return resp.json() def run_agent(user_input: str): skills load_skills() tool_defs [s[tool_def] for s in skills] messages [ {role: system, content: 你是一個智能助手可以根據(jù)用戶需求調(diào)用可用技能完成任務(wù)。}, {role: user, content: user_input}, ] # 第一次調(diào)用讓模型決定是否調(diào)用工具 response call_llm(messages, tool_defs) message response[choices][0][message] messages.append(message) # 如果模型請求調(diào)用工具就執(zhí)行 if message.get(tool_calls): for tool_call in message[tool_calls]: fn_name tool_call[function][name] fn_args json.loads(tool_call[function][arguments]) print(f[Agent] 調(diào)用 Skill: {fn_name}, 參數(shù): {fn_args}) result execute_skill(fn_name, fn_args) messages.append({ role: tool, tool_call_id: tool_call[id], content: json.dumps(result, ensure_asciiFalse), }) # 把工具結(jié)果交給模型生成最終回復(fù) final_response call_llm(messages, tool_defs) return final_response[choices][0][message][content] # 如果模型認為不需要調(diào)用工具直接返回 return message.get(content, ) if __name__ __main__: test_input input(請輸入你的問題) answer run_agent(test_input) print(f\n[Assistant] {answer})這個主循環(huán)演示了 Agent 最核心的機制先讓模型看用戶輸入和技能列表決定是否需要調(diào)用 Skill如果需要執(zhí)行代碼拿到結(jié)果再把結(jié)果回傳給模型生成最終回復(fù)。這就是 ReAct 模式中最基礎(chǔ)的“思考-行動-觀察”循環(huán)只不過這里把“行動”抽象成了 Skill 調(diào)用。文件路徑requirements.txtrequests安裝依賴并配置環(huán)境變量后就可以運行了pip install -r requirements.txt export LLM_API_KEY你的API密鑰 export LLM_BASE_URLhttps://你的模型服務(wù)地址/v1 export LLM_MODEL你的模型名稱 python agent.py7. 運行結(jié)果與效果驗證7.1 運行方式啟動后在命令行輸入一段需要調(diào)用 Skill 的話。比如請輸入你的問題請幫我格式化下面這段JSON{name:agent,version:1.0,skills:[json_formatter,text_summarizer]}7.2 預(yù)期輸出如果一切正常你會看到類似下面的輸出[Agent] 調(diào)用 Skill: json_formatter, 參數(shù): {action: format, json_str: {name:agent,version:1.0,skills:[json_formatter,text_summarizer]}} [Assistant] 格式化后的 JSON 如下 { name: agent, version: 1.0, skills: [ json_formatter, text_summarizer ] }再試一個需要總結(jié)文本的問題請輸入你的問題幫我總結(jié)一下這段話Agent Skill 是一種將提示詞、工具調(diào)用邏輯和領(lǐng)域知識封裝成可復(fù)用能力單元的技術(shù)方案它讓開發(fā)團隊能夠像管理代碼庫一樣管理 AI Agent 的能力模塊……此時 Agent 應(yīng)該調(diào)用text_summarizer并返回一段摘要。7.3 驗證成功的關(guān)鍵指標判斷一個 Skill 接入是否成功可以從三個層面驗證第一模型是否正確選擇了 Skill。用戶輸入“格式化 JSON”模型應(yīng)該調(diào)用json_formatter而不是直接回答或調(diào)用其他 Skill。如果選擇錯了優(yōu)先排查 SKILL.md 的觸發(fā)條件寫得是否清楚。第二Skill 執(zhí)行結(jié)果是否正確。在execute_skill返回后可以直接打印 result 檢查。這一步排除模型問題專門驗證代碼邏輯。第三最終回復(fù)是否基于工具結(jié)果。理想的 Agent 回復(fù)應(yīng)該引用工具執(zhí)行后的內(nèi)容而不是模型憑空編造。如果模型忽略了工具結(jié)果檢查 messages 里 tool 消息的格式是否正確。如果運行失敗第一步先看終端里的報錯是發(fā)生在“模型調(diào)用”階段還是“Skill 執(zhí)行”階段。模型調(diào)用失敗通常是 API 地址、密鑰或網(wǎng)絡(luò)問題Skill 執(zhí)行失敗通常是代碼異常或參數(shù)格式不匹配。8. 常見問題與排查思路下面整理了 Agent Skill 開發(fā)中最高頻的幾類問題按排查優(yōu)先級排列。問題現(xiàn)象可能原因排查方式解決方案模型沒有調(diào)用任何 Skill技能描述不清晰模型不知道何時使用檢查 SKILL.md 的觸發(fā)條件是否具體重寫描述明確觸發(fā)場景和輸入輸出模型調(diào)用了錯誤的 Skill多個 Skill 邊界重疊檢查各 Skill 描述是否存在歧義收緊邊界增加反例說明“何時不要使用”工具參數(shù)解析失敗模型生成的參數(shù)與 Schema 不匹配打印 tool_call 的原始 arguments在 Schema 中增加必填字段類型約束調(diào)用大模型 API 超時網(wǎng)絡(luò)問題或模型響應(yīng)過慢先單獨測試直接調(diào)用模型接口增加超時重試或換用更快的小模型Skill 返回內(nèi)容被模型忽略tool 消息格式不正確檢查 messages 中 tool 消息的 tool_call_id 是否匹配確保 tool_call_id 與模型返回的 id 一致多個 Skill 加載后 token 超限工具描述過長統(tǒng)計每個 SKILL.md 的長度精簡描述只保留觸發(fā)條件和使用說明生產(chǎn)環(huán)境 Skill 更新后行為異常版本未隔離檢查部署流程是否用了緩存為 Skill 增加版本號支持灰度發(fā)布這里重點說兩個問題。第一個是“模型不調(diào)用 Skill”。大多數(shù)情況下不是代碼問題而是描述文件寫得不夠清楚。模型就像一個沒有經(jīng)驗的實習生你寫的說明書越模糊它越不敢動手。優(yōu)化方法是給描述增加“觸發(fā)條件”和“不要使用”兩個小節(jié)用正反例把邊界框住。第二個是“參數(shù)解析失敗”。模型返回的 tool_calls 中arguments 是一個 JSON 字符串但模型偶爾會生成缺失字段或類型不符的內(nèi)容。穩(wěn)妥的做法是在解析時做容錯比如用 try-except 包裹 json.loads解析失敗時返回錯誤信息讓模型重新生成。9. 最佳實踐與工程建議9.1 Skill 命名與描述規(guī)范命名要遵循“動詞 名詞”的結(jié)構(gòu)例如json_formatter、text_summarizer、order_query。命名本身要能直接反映技能功能避免使用utils、helper、misc這類模糊詞匯。描述文件建議使用固定模板至少包含觸發(fā)條件、使用說明、注意事項、示例四部分。團隊內(nèi)部可以維護一份 SKILL.md 模板新成員照著填就行。示例部分容易被忽略但對模型理解非常關(guān)鍵一定要寫。9.2 上下文長度控制Skill 描述最終會注入模型上下文描述越長token 消耗越大。一個 1024 字符的 SKILL.md 大約消耗 300 到 500 token如果加載 20 個 Skill光是工具定義就可能達到上萬 token。優(yōu)化思路有三個方向一是精簡描述只保留必要信息二是按按需加載先給模型展示精簡版描述觸發(fā)后再加載完整版三是分組分類不同場景只加載對應(yīng)分組的 Skill。后兩種方案工程復(fù)雜度更高但效果明顯。9.3 安全邊界Skill 是代碼意味著它有執(zhí)行任意操作的能力。在真實項目中必須非常謹慎涉及數(shù)據(jù)庫操作、文件刪除、系統(tǒng)命令的 Skill必須顯式聲明權(quán)限級別生產(chǎn)環(huán)境禁止 Skill 直接執(zhí)行未經(jīng)確認的寫操作Skill 的輸入?yún)?shù)來自模型生成的 JSON本質(zhì)上是不可信的外部輸入要做參數(shù)校驗和長度限制所有涉及敏感操作的 Skill建議加入人工確認或二次授權(quán)機制。權(quán)限設(shè)計遵循最小原則能只讀就不要給寫權(quán)限能只操作單個資源就不要給全量權(quán)限。9.4 版本管理與發(fā)布把 Skill 當代碼來管理。每個 Skill 目錄內(nèi)建議維護一個版本號發(fā)布流程可以這樣設(shè)計開發(fā)環(huán)境直接修改源碼聯(lián)調(diào)測試測試環(huán)境加載指定版本號的 Skill 副本跑回歸用例生產(chǎn)環(huán)境發(fā)布新版本后觀察監(jiān)控指標出現(xiàn)問題立即回滾舊版本。如果團隊 Skill 數(shù)量超過幾十個建議引入專門的技能倉庫用統(tǒng)一的 CLI 工具管理 Skill 的創(chuàng)建、測試、發(fā)布和版本記錄。9.5 日志與可觀測性Agent 應(yīng)用的黑盒屬性很強必須記錄足夠多的日志才能定位問題。每次 Skill 調(diào)用至少記錄以下信息用戶輸入摘要模型決定調(diào)用的 Skill 名稱和參數(shù)Skill 執(zhí)行結(jié)果和耗時最終回復(fù)的生成情況。記錄格式建議采用結(jié)構(gòu)化 JSON方便后續(xù)分析和監(jiān)控。線上問題排查時這些日志能幫你快速還原“模型當時看到了什么、做了什么、結(jié)果是什么”的完整鏈路。10. 總結(jié)與后續(xù)學習方向Agent Skill 是 AI 大模型應(yīng)用開發(fā)中從“能調(diào)用模型”走向“能構(gòu)建 Agent 產(chǎn)品”的關(guān)鍵一環(huán)。從材料來看當前大模型應(yīng)用開發(fā)的核心競爭點正在從模型本身轉(zhuǎn)向外圍工程能力Skill 作為能力封裝的標準化單元會越來越重要。現(xiàn)在回顧一下這篇文章真正講清楚的幾個點Skill 和 Agent 的分層關(guān)系——Agent 負責決策Skill 負責執(zhí)行Skill 和 MCP 的協(xié)同關(guān)系——MCP 管連接Skill 管封裝Skill 的目錄結(jié)構(gòu)和描述文件設(shè)計一個完整的可運行的 Python 示例以及生產(chǎn)環(huán)境中的安全、版本和可觀測性要求。下一步建議你按這個順序繼續(xù)深入第一把本文的示例代碼跑通然后自己新增一個 Skill。不要復(fù)制粘貼就完事試著改一改 SKILL.md 的描述觀察模型行為的變化。第二嘗試用 Dify、FastGPT 或 Coze 這類平臺實現(xiàn)同樣的流程。平臺上的“技能”或“插件”配置底層邏輯和本文講的基本一致用平臺實現(xiàn)一遍能幫你把抽象概念具體化。第三深入研究 Agent 主循環(huán)的更多模式。本文只演示了最簡單的單輪工具調(diào)用實際產(chǎn)品往往需要多輪工具調(diào)用、反思重試、人機協(xié)同這些都是在基礎(chǔ)循環(huán)上疊加的復(fù)雜度。第四如果你在考慮 MCP可以先從一個官方或社區(qū)現(xiàn)成的 MCP Server 入手理解 MCP 的消息格式和生命周期再把 MCP 接入到自己的 Skill 體系里。畢竟 Skill 是封裝MCP 是通道兩者結(jié)合才是生產(chǎn)級方案。AI 大模型領(lǐng)域變化很快但“把復(fù)雜任務(wù)拆解成能力單元再用智能體編排它們”的思路短期內(nèi)不會過時。你現(xiàn)在花時間把 Skill 的底層機制搞清楚以后無論哪個新框架出來都能快速上手。建議收藏本文遇到概念混淆或工程問題的時候翻出來對照會比重新搜索一堆碎片資料高效得多。 Agent Skill 實戰(zhàn)：從零開發(fā)可復(fù)用技能，理清與 MCP、Tool 的區(qū)別
從 2025 年初開始“Agent Skill”這個詞在 AI 大模型開發(fā)圈子里的出現(xiàn)頻率越來越高。但打開網(wǎng)上的教程你會發(fā)現(xiàn)一個很尷尬的現(xiàn)象講 Agent 概念的文章鋪天蓋地一旦深入到 Skill 怎么設(shè)計、怎么寫、怎么調(diào)試內(nèi)容就斷崖式減少。更讓人頭疼的是Skill、Agent、Tool、MCP 這四個概念經(jīng)常被混在一起講讀完反而更迷糊。這篇文章不想復(fù)述概念而是想解決三個具體問題第一把 Skill 和 Agent、Tool、MCP 的關(guān)系徹底講清楚尤其是“Skill 和 MCP 有什么區(qū)別”這個高頻疑問第二用一套最小但完整的 Python 代碼演示如何從零開發(fā)一個 Skill并讓 Agent 在對話中自動選擇和使用它第三把開發(fā)過程中真正容易踩的坑和工程化建議整理成清單方便你直接用到項目里。核心判斷先放在前面Skill 不是 Agent 的另一個名字也不是 MCP 的替代品。Skill 解決的是“能力封裝與復(fù)用”的問題MCP 解決的是“能力接入與互通”的問題Agent 才是那個負責“決策與調(diào)度”的主體。理解了這個分層你再看任何 Agent 框架都會順暢很多。1. 這篇文章真正要解決的問題先說說為什么 Agent Skill 值得單獨寫一篇長文。很多人已經(jīng)會調(diào)用大模型 API寫一個聊天程序并不難把用戶問題拼進 Prompt調(diào)用 Chat Completion 接口拿到結(jié)果返回給前端。這算 AI 應(yīng)用但還稱不上 Agent 應(yīng)用。Agent 和普通聊天的本質(zhì)區(qū)別在于 Agent 有自主規(guī)劃、工具調(diào)用和任務(wù)執(zhí)行的能力。而 Skill 就是“工具調(diào)用能力”的一種高級封裝形態(tài)。如果你只會在代碼里寫死調(diào)用某一個函數(shù)那 Agent 的“自主性”是不存在的只有把能力抽象成 Skill讓模型根據(jù)用戶意圖去匹配和調(diào)用Agent 才算真正“活”起來。從行業(yè)趨勢看AI 大模型應(yīng)用開發(fā)正在經(jīng)歷一個明顯的轉(zhuǎn)折基礎(chǔ)模型的能力差距在縮小真正拉開產(chǎn)品體驗差距的是模型外圍的工程能力——知識庫怎么組織、工具怎么接入、技能怎么沉淀、流程怎么編排。Skill 恰好是這條鏈路里承上啟下的關(guān)鍵一環(huán)。所以這篇文章的讀者畫像很明確已經(jīng)會調(diào)用大模型 API但想進一步做 Agent 應(yīng)用開發(fā)的開發(fā)者用過 Dify、FastGPT、Coze 等平臺但不滿足于拖拽配置想理解底層運行機制的人團隊里需要多人協(xié)作開發(fā) Agent 功能想統(tǒng)一管理“能力塊”的技術(shù)負責人正在糾結(jié) MCP 和 Skill 怎么選不知道它們適用邊界的初學者。如果你屬于其中任何一類這篇文章會給你一條從概念到落地的完整路徑。我們會先建立認知框架再寫代碼再講排錯最后給工程化建議。2. Agent Skill 核心概念它到底是什么2.1 從 Tool 到 Skill 的演進邏輯要理解 Skill得先理解它從哪來。在最早的 Agent 實現(xiàn)里開發(fā)者會把“工具”以函數(shù)形式注冊給模型。比如一個天氣查詢函數(shù)get_weather(city: string) - string模型在對話中檢測到用戶想查天氣就生成一個函數(shù)調(diào)用請求由代碼執(zhí)行后把結(jié)果返回給模型。這是 Function Calling 的標準流程也是現(xiàn)在所有 Agent 框架的底座。這種方式在小規(guī)模場景下沒有問題但一旦工具多起來問題就出現(xiàn)了每個工具都只是“一個函數(shù)”缺少使用說明和邊界描述模型經(jīng)常用錯一個完整任務(wù)往往需要多個函數(shù)配合比如“先查天氣再根據(jù)天氣推薦穿搭”這種組合邏輯沒有地方放工具的 Prompt 說明散落在系統(tǒng)提示詞里維護成本越來越高。Skill 的出現(xiàn)就是為了解決這些問題。它把“一組相關(guān)的指令、說明、代碼和資源”打包成一個獨立的、可復(fù)用的單元。你可以把 Skill 理解成一個自帶說明書的能力模塊模型看到 Skill 的描述后知道什么時候該用它、怎么用、有哪些注意事項。用生活場景類比Tool 是工具箱里的一把螺絲刀Skill 是一本“如何拆裝一臺電腦”的圖文教程里面既有工具清單也有操作步驟還有常見問題的處理方法。Agent 拿到任務(wù)后不是自己去翻工具箱而是先看教程再按教程里的指引執(zhí)行。2.2 Skill 與 Agent 的區(qū)別這是很多人最容易混淆的一組概念。Agent 是決策主體它負責接收任務(wù)、拆解計劃、調(diào)用能力、判斷結(jié)果是否達標、決定下一步動作。Agent 是一個“運行中的智能體”它有狀態(tài)、有上下文、有循環(huán)邏輯。Skill 是能力單元它是被 Agent 調(diào)用的“技能包”。Skill 本身沒有決策能力它只負責把一件事做好。比如“把 Markdown 轉(zhuǎn)成 PDF”“調(diào)用數(shù)據(jù)庫查詢用戶訂單”“對一段文本做情感分析”這些都可以是獨立的 Skill。打個比方Agent 是一個廚師Skill 是廚師掌握的做菜技能。廚師Agent決定今天做什么菜、先做哪道、火候怎么控制技能Skill負責具體的操作流程比如“紅燒肉怎么做”“清蒸魚怎么處理”。技能本身不會想問題但它知道怎么把事情執(zhí)行到位。在實際代碼里這種區(qū)別體現(xiàn)為Agent 是一個循環(huán)loop里面有規(guī)劃、調(diào)用、觀察、反思Skill 是一組注冊好的能力描述和實現(xiàn)函數(shù)Agent 在循環(huán)里根據(jù)用戶需求去匹配它們。2.3 Skill 與 MCP 的區(qū)別“agent skill 和 mcp有什么區(qū)別”是近期的熱門搜索詞說明很多人在這兩個概念上卡住了。簡單直接地說MCPModel Context Protocol是一種標準協(xié)議它解決的是“模型怎么連接到外部工具和數(shù)據(jù)源”的問題。你可以把它理解為 USB-C 接口標準——不管是什么設(shè)備只要遵守這個接口規(guī)范就能互相連接。MCP Server 負責把工具暴露給客戶端MCP Client 負責跟 Server 通信。Skill 是一種能力封裝它解決的是“這個能力怎么被正確地使用”的問題。Skill 里可以包含提示詞、使用說明、示例、代碼邏輯甚至也可以是 MCP Server 的配置。兩者不是競爭關(guān)系而是不同層次的東西。一個 Skill 內(nèi)部完全可以依賴 MCP 去調(diào)用遠程工具。MCP 管“連接”Skill 管“封裝”。用表格對比更清晰對比維度Agent SkillMCP本質(zhì)能力封裝單元標準化連接協(xié)議解決問題如何讓模型正確使用復(fù)雜能力如何讓模型接入外部工具和數(shù)據(jù)主要內(nèi)容提示詞、說明、代碼、資源工具定義、傳輸協(xié)議、服務(wù)端/客戶端能否獨立運行需要被 Agent 加載后調(diào)用服務(wù)端可獨立運行客戶端負責接入典型場景把領(lǐng)域知識工具邏輯打包成技能統(tǒng)一的工具接入網(wǎng)關(guān)結(jié)論很明確做 Agent 應(yīng)用時Skill 和 MCP 不是二選一而是協(xié)同使用。先用 MCP 把工具接進來再用 Skill 告訴模型怎么用好這些工具。2.4 Skill 與 Plugin、Workflow 的關(guān)系還有一個容易混淆的點是 Skill、Plugin、Workflow 的邊界。Plugin 更偏向“應(yīng)用擴展”通常包含完整的用戶界面和交互邏輯比如瀏覽器插件、IDE 插件。在 Agent 語境下Plugin 往往被用作“可插拔功能包”的統(tǒng)稱Skill 可以理解為 Plugin 的一種更聚焦、更面向模型的設(shè)計形態(tài)。Workflow 則是“固定流程編排”它強調(diào)步驟和順序比如“先查庫存再下訂單最后發(fā)通知”。Workflow 通常是確定性的每一步做什么是預(yù)先定義好的。Skill 則更靈活它更像一個“可以被模型按需調(diào)用的能力包”模型會根據(jù)當前上下文決定是否使用、如何使用。一句話總結(jié)Workflow 是寫好的劇本Skill 是演員掌握的技能。劇本規(guī)定了每一幕怎么演技能讓演員在即興發(fā)揮時也能不砸場。3. 為什么需要 Agent Skill工程化視角的三個理由3.1 提示詞膨脹問題做 Agent 應(yīng)用的人遲早會遇到這個問題系統(tǒng)提示詞越寫越長。一開始只有角色設(shè)定后來加上工具說明再后來加上各種注意事項、格式要求、示例最后 Prompt 達到幾千 token每次請求的延遲和成本都在漲。Skill 提供了一種拆分思路把不同能力的說明從系統(tǒng)提示詞中拆出去只在 Agent 需要時按需加載描述真正執(zhí)行時才把完整內(nèi)容注入上下文。這樣系統(tǒng)提示詞保持精簡模型每次只需要關(guān)注當前任務(wù)相關(guān)的 Skill 內(nèi)容既省錢又更精準。從這里能看出 Skill 的另一個價值它讓“上下文管理”從黑盒變成了結(jié)構(gòu)化操作。哪些 Skill 被加載了、加載了哪些內(nèi)容、占了多少 token都是可統(tǒng)計、可優(yōu)化的。3.2 能力復(fù)用與團隊協(xié)作在一個團隊里不同業(yè)務(wù)線可能需要相似的能力。比如“文本總結(jié)”這個能力客服機器人要用內(nèi)容審核要用數(shù)據(jù)分析助手也要用。如果沒有 Skill 機制每個項目各寫各的 Prompt 和調(diào)用邏輯很快就會出現(xiàn)三種效果不一致的實現(xiàn)還互相不知道。Skill 把能力沉淀成一個獨立模塊后團隊可以像管理代碼庫一樣管理技能庫。新增一個業(yè)務(wù)場景時先查一下技能庫有沒有現(xiàn)成的 Skill有就直接引用沒有就開發(fā)一個并提交入庫。這種模式大大降低了重復(fù)開發(fā)成本。3.3 讓 Agent 的“技能”可測試、可回滾這是 Skill 最容易被忽視的工程價值。如果你把能力邏輯寫死在 Agent 主流程里想測一個新方案只能改主流程代碼影響面大、回歸成本高。但 Skill 是獨立單元你可以單獨給它構(gòu)造輸入輸出做單元測試可以在生產(chǎn)和測試環(huán)境加載不同版本的 Skill出問題后可以快速回滾到上一個版本而不影響 Agent 主體。這就把 Agent 開發(fā)從“調(diào) Prompt 玄學”推向更接近傳統(tǒng)軟件工程的狀態(tài)模塊化、可測試、可版本化。4. 環(huán)境準備與前置條件4.1 技術(shù)棧選擇本文的示例代碼使用 Python 3這是目前 AI 大模型應(yīng)用開發(fā)最主流的語言相關(guān)生態(tài)最成熟。版本方面以實際項目為準建議 Python 3.10 以上本文代碼沒有依賴任何特定框架只使用標準庫和 requests 庫方便你理解底層原理。如果你平時用 Java、Node.js文章后面的設(shè)計思路同樣適用只是代碼示例需要用對應(yīng)語言改寫。4.2 大模型 API 準備示例中的“文本總結(jié) Skill”需要調(diào)用大模型 API。你可以選擇任意兼容 OpenAI 接口格式的服務(wù)包括國內(nèi)主流大模型廠商的 API或者本地部署的模型服務(wù)。關(guān)鍵點只有一個API 地址和密鑰通過環(huán)境變量配置不要寫死在代碼里。本文為了聚焦知識點統(tǒng)一使用 OpenAI 風格的接口調(diào)用方式。你只需要替換 base_url 和 api_key 即可。如果本地部署了模型也可以把 base_url 指向本地服務(wù)。4.3 項目目錄結(jié)構(gòu)我們用一個最小但完整的目錄來承載示例agent-skill-demo/ ├── requirements.txt ├── skills/ │ ├── json_formatter/ │ │ ├── SKILL.md │ │ └── skill.py │ └── text_summarizer/ │ ├── SKILL.md │ └── skill.py ├── agent.py └── skill_loader.py這個結(jié)構(gòu)體現(xiàn)的是 Skill 的核心設(shè)計思想每個 Skill 一個目錄目錄內(nèi)包含說明文件SKILL.md和實現(xiàn)代碼skill.py。Agent 運行前通過 loader 掃描 skills 目錄解析每個 SKILL.md把技能描述注冊給模型當模型決定調(diào)用某個 Skill 時loader 再執(zhí)行對應(yīng)的 skill.py。5. 核心流程拆解從零開發(fā)一個 Skill 的完整過程開發(fā)一個 Skill 通常分四步定義邊界、編寫描述、實現(xiàn)邏輯、注冊加載。每一步都有設(shè)計問題需要注意。5.1 第一步定義 Skill 的邊界這是最容易被忽略卻最重要的一步。一個 Skill 應(yīng)該只做一件事并且邊界清晰。不好的例子做一個“數(shù)據(jù)處理 Skill”里面既做 JSON 格式化又做文本總結(jié)還做數(shù)據(jù)可視化。這個 Skill 的描述沒法寫清楚模型也不知道什么時候該用它。好的例子把“JSON 格式化”單獨做成一個 Skill描述里寫清楚“當用戶提供一段 JSON 字符串并希望進行格式化、校驗或壓縮時使用此 Skill”。邊界清晰模型才能準確匹配。定義邊界的判斷標準很簡單你能否用一句話說清楚這個 Skill 在什么條件下被觸發(fā)如果說不清楚說明邊界有問題。5.2 第二步編寫技能描述文件Skill 的描述文件是整個機制的“說明書”。它的質(zhì)量直接決定模型能不能正確使用這個 Skill。一份好的描述文件至少包含以下內(nèi)容技能名稱簡短、準確觸發(fā)條件什么情況下模型應(yīng)該使用這個技能使用說明如何調(diào)用輸入?yún)?shù)是什么輸出是什么注意事項什么情況下不要使用有什么限制示例給一個輸入輸出示例幫助模型理解。記住一個原則描述文件是寫給模型看的不是寫給開發(fā)者看的。你是在教一個聰明但沒有經(jīng)驗的實習生怎么使用工具而不是在寫給自己看的代碼注釋。5.3 第三步實現(xiàn)執(zhí)行邏輯Skill 的執(zhí)行邏輯就是普通 Python 函數(shù)接收輸入返回結(jié)果。關(guān)鍵設(shè)計點是輸入輸出要結(jié)構(gòu)化方便 Agent 主循環(huán)解析。推薦統(tǒng)一采用字典結(jié)構(gòu)至少包含 status、result 兩個字段方便判斷成功或失敗。5.4 第四步注冊與加載Agent 啟動時會掃描 skills 目錄讀取所有 SKILL.md把其中的描述信息轉(zhuǎn)換成模型可識別的工具定義格式OpenAI 風格的 functions 或 tools。這一步相當于把“技能說明書”裝進模型的工具列表里。模型在對話中看到這些技能描述后會根據(jù)用戶意圖生成調(diào)用請求Agent 執(zhí)行對應(yīng)函數(shù)再把結(jié)果返回給模型繼續(xù)推理。6. 完整示例代碼實戰(zhàn)6.1 示例一JSON 格式化 Skill先實現(xiàn)一個最簡單但完整的 Skill。文件路徑skills/json_formatter/SKILL.md# JSON Formatter ## 觸發(fā)條件 當用戶要求對 JSON 字符串進行格式化、壓縮、校驗或解析時使用。 ## 使用說明 輸入?yún)?shù) - action: 必填取值 format格式化或 compress壓縮 - json_str: 必填待處理的 JSON 字符串 輸出 - 格式化或壓縮后的 JSON 字符串 - 如果 JSON 解析失敗返回錯誤信息 ## 注意事項 不要在用戶沒有明確要求 JSON 處理時使用此技能。文件路徑skills/json_formatter/skill.pyimport json def run(params: dict) - dict: action params.get(action) json_str params.get(json_str, ) if not action or not json_str: return {status: error, result: 缺少 action 或 json_str 參數(shù)} try: data json.loads(json_str) except json.JSONDecodeError as e: return {status: error, result: fJSON 解析失敗: {e}} if action format: result json.dumps(data, ensure_asciiFalse, indent2) elif action compress: result json.dumps(data, ensure_asciiFalse, separators(,, :)) else: return {status: error, result: f不支持的 action: {action}} return {status: success, result: result}這段代碼的邏輯很簡單先解析 JSON 驗證合法性再根據(jù) action 決定是格式化還是壓縮。注意這里的返回結(jié)構(gòu)是統(tǒng)一的字典格式Agent 主循環(huán)拿到 status 為 success 或 error 后可以決定把結(jié)果交給模型還是觸發(fā)錯誤處理。6.2 示例二調(diào)用大模型的文本總結(jié) Skill第二個示例演示 Skill 內(nèi)部如何調(diào)用大模型這是實際開發(fā)中最常見的形態(tài)。文件路徑skills/text_summarizer/SKILL.md# Text Summarizer ## 觸發(fā)條件 當用戶要求對一段較長的文本進行摘要、總結(jié)、提煉要點時使用。 ## 使用說明 輸入?yún)?shù) - text: 必填需要總結(jié)的文本內(nèi)容 - max_length: 可選總結(jié)的最大字數(shù)默認 200 輸出 - 對原文的總結(jié)內(nèi)容 ## 注意事項 - 文本過長時優(yōu)先截取核心部分再調(diào)用模型 - 不要對代碼、JSON 等結(jié)構(gòu)化內(nèi)容使用此技能文件路徑skills/text_summarizer/skill.pyimport os import requests def run(params: dict) - dict: text params.get(text, ) max_length params.get(max_length, 200) if not text: return {status: error, result: 缺少 text 參數(shù)} api_key os.getenv(LLM_API_KEY) base_url os.getenv(LLM_BASE_URL, https://api.openai.com/v1) model os.getenv(LLM_MODEL, gpt-4o-mini) prompt f請對下面的文本進行總結(jié)不超過 {max_length} 字\n\n{text} try: resp requests.post( f{base_url}/chat/completions, headers{Authorization: fBearer {api_key}}, json{ model: model, messages: [{role: user, content: prompt}], temperature: 0.3, }, timeout60, ) resp.raise_for_status() summary resp.json()[choices][0][message][content] return {status: success, result: summary} except Exception as e: return {status: error, result: f調(diào)用模型失敗: {e}}這個 Skill 演示了一個關(guān)鍵設(shè)計Skill 內(nèi)部也可以調(diào)用模型但 Skill 本身不負責“決定做什么”只負責“把總結(jié)這件事做好”。模型 API 地址、密鑰、模型名全部通過環(huán)境變量讀取這是生產(chǎn)環(huán)境的最低要求。6.3 示例三Skill 加載器與 Agent 主循環(huán)前面兩個 Skill 是獨立的現(xiàn)在需要把它們接入 Agent。先寫一個加載器。文件路徑skill_loader.pyimport importlib.util import os from pathlib import Path SKILLS_DIR Path(__file__).parent / skills def _read_skill_md(skill_dir: Path) - str: md_path skill_dir / SKILL.md if not md_path.exists(): return return md_path.read_text(encodingutf-8) def load_skills(): skills [] if not SKILLS_DIR.exists(): return skills for skill_dir in SKILLS_DIR.iterdir(): if not skill_dir.is_dir(): continue description _read_skill_md(skill_dir) if not description: continue # 將 SKILL.md 轉(zhuǎn)成模型工具描述 tool_def { type: function, function: { name: skill_dir.name, description: description[:1024], parameters: { type: object, properties: { action: {type: string}, json_str: {type: string}, text: {type: string}, max_length: {type: integer}, } }, }, } skills.append({name: skill_dir.name, tool_def: tool_def, path: skill_dir}) return skills def execute_skill(skill_name: str, params: dict) - dict: skill_dir SKILLS_DIR / skill_name py_path skill_dir / skill.py if not py_path.exists(): return {status: error, result: fSkill {skill_name} 不存在} spec importlib.util.spec_from_file_location(skill_name, py_path) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) return module.run(params)這里為了方便演示把參數(shù) schema 寫死成了所有 Skill 的并集。實際項目中推薦讓每個 SKILL.md 里的 YAML front-matter 聲明自己的參數(shù) schemaloader 動態(tài)解析這里不做過度展開。接著寫 Agent 主循環(huán)。文件路徑agent.pyimport json import os import requests from skill_loader import load_skills, execute_skill def call_llm(messages, tools): api_key os.getenv(LLM_API_KEY) base_url os.getenv(LLM_BASE_URL, https://api.openai.com/v1) model os.getenv(LLM_MODEL, gpt-4o-mini) payload { model: model, messages: messages, tools: tools, tool_choice: auto, temperature: 0.3, } resp requests.post( f{base_url}/chat/completions, headers{Authorization: fBearer {api_key}}, jsonpayload, timeout120, ) resp.raise_for_status() return resp.json() def run_agent(user_input: str): skills load_skills() tool_defs [s[tool_def] for s in skills] messages [ {role: system, content: 你是一個智能助手可以根據(jù)用戶需求調(diào)用可用技能完成任務(wù)。}, {role: user, content: user_input}, ] # 第一次調(diào)用讓模型決定是否調(diào)用工具 response call_llm(messages, tool_defs) message response[choices][0][message] messages.append(message) # 如果模型請求調(diào)用工具就執(zhí)行 if message.get(tool_calls): for tool_call in message[tool_calls]: fn_name tool_call[function][name] fn_args json.loads(tool_call[function][arguments]) print(f[Agent] 調(diào)用 Skill: {fn_name}, 參數(shù): {fn_args}) result execute_skill(fn_name, fn_args) messages.append({ role: tool, tool_call_id: tool_call[id], content: json.dumps(result, ensure_asciiFalse), }) # 把工具結(jié)果交給模型生成最終回復(fù) final_response call_llm(messages, tool_defs) return final_response[choices][0][message][content] # 如果模型認為不需要調(diào)用工具直接返回 return message.get(content, ) if __name__ __main__: test_input input(請輸入你的問題) answer run_agent(test_input) print(f\n[Assistant] {answer})這個主循環(huán)演示了 Agent 最核心的機制先讓模型看用戶輸入和技能列表決定是否需要調(diào)用 Skill如果需要執(zhí)行代碼拿到結(jié)果再把結(jié)果回傳給模型生成最終回復(fù)。這就是 ReAct 模式中最基礎(chǔ)的“思考-行動-觀察”循環(huán)只不過這里把“行動”抽象成了 Skill 調(diào)用。文件路徑requirements.txtrequests安裝依賴并配置環(huán)境變量后就可以運行了pip install -r requirements.txt export LLM_API_KEY你的API密鑰 export LLM_BASE_URLhttps://你的模型服務(wù)地址/v1 export LLM_MODEL你的模型名稱 python agent.py7. 運行結(jié)果與效果驗證7.1 運行方式啟動后在命令行輸入一段需要調(diào)用 Skill 的話。比如請輸入你的問題請幫我格式化下面這段JSON{name:agent,version:1.0,skills:[json_formatter,text_summarizer]}7.2 預(yù)期輸出如果一切正常你會看到類似下面的輸出[Agent] 調(diào)用 Skill: json_formatter, 參數(shù): {action: format, json_str: {name:agent,version:1.0,skills:[json_formatter,text_summarizer]}} [Assistant] 格式化后的 JSON 如下 { name: agent, version: 1.0, skills: [ json_formatter, text_summarizer ] }再試一個需要總結(jié)文本的問題請輸入你的問題幫我總結(jié)一下這段話Agent Skill 是一種將提示詞、工具調(diào)用邏輯和領(lǐng)域知識封裝成可復(fù)用能力單元的技術(shù)方案它讓開發(fā)團隊能夠像管理代碼庫一樣管理 AI Agent 的能力模塊……此時 Agent 應(yīng)該調(diào)用text_summarizer并返回一段摘要。7.3 驗證成功的關(guān)鍵指標判斷一個 Skill 接入是否成功可以從三個層面驗證第一模型是否正確選擇了 Skill。用戶輸入“格式化 JSON”模型應(yīng)該調(diào)用json_formatter而不是直接回答或調(diào)用其他 Skill。如果選擇錯了優(yōu)先排查 SKILL.md 的觸發(fā)條件寫得是否清楚。第二Skill 執(zhí)行結(jié)果是否正確。在execute_skill返回后可以直接打印 result 檢查。這一步排除模型問題專門驗證代碼邏輯。第三最終回復(fù)是否基于工具結(jié)果。理想的 Agent 回復(fù)應(yīng)該引用工具執(zhí)行后的內(nèi)容而不是模型憑空編造。如果模型忽略了工具結(jié)果檢查 messages 里 tool 消息的格式是否正確。如果運行失敗第一步先看終端里的報錯是發(fā)生在“模型調(diào)用”階段還是“Skill 執(zhí)行”階段。模型調(diào)用失敗通常是 API 地址、密鑰或網(wǎng)絡(luò)問題Skill 執(zhí)行失敗通常是代碼異常或參數(shù)格式不匹配。8. 常見問題與排查思路下面整理了 Agent Skill 開發(fā)中最高頻的幾類問題按排查優(yōu)先級排列。問題現(xiàn)象可能原因排查方式解決方案模型沒有調(diào)用任何 Skill技能描述不清晰模型不知道何時使用檢查 SKILL.md 的觸發(fā)條件是否具體重寫描述明確觸發(fā)場景和輸入輸出模型調(diào)用了錯誤的 Skill多個 Skill 邊界重疊檢查各 Skill 描述是否存在歧義收緊邊界增加反例說明“何時不要使用”工具參數(shù)解析失敗模型生成的參數(shù)與 Schema 不匹配打印 tool_call 的原始 arguments在 Schema 中增加必填字段類型約束調(diào)用大模型 API 超時網(wǎng)絡(luò)問題或模型響應(yīng)過慢先單獨測試直接調(diào)用模型接口增加超時重試或換用更快的小模型Skill 返回內(nèi)容被模型忽略tool 消息格式不正確檢查 messages 中 tool 消息的 tool_call_id 是否匹配確保 tool_call_id 與模型返回的 id 一致多個 Skill 加載后 token 超限工具描述過長統(tǒng)計每個 SKILL.md 的長度精簡描述只保留觸發(fā)條件和使用說明生產(chǎn)環(huán)境 Skill 更新后行為異常版本未隔離檢查部署流程是否用了緩存為 Skill 增加版本號支持灰度發(fā)布這里重點說兩個問題。第一個是“模型不調(diào)用 Skill”。大多數(shù)情況下不是代碼問題而是描述文件寫得不夠清楚。模型就像一個沒有經(jīng)驗的實習生你寫的說明書越模糊它越不敢動手。優(yōu)化方法是給描述增加“觸發(fā)條件”和“不要使用”兩個小節(jié)用正反例把邊界框住。第二個是“參數(shù)解析失敗”。模型返回的 tool_calls 中arguments 是一個 JSON 字符串但模型偶爾會生成缺失字段或類型不符的內(nèi)容。穩(wěn)妥的做法是在解析時做容錯比如用 try-except 包裹 json.loads解析失敗時返回錯誤信息讓模型重新生成。9. 最佳實踐與工程建議9.1 Skill 命名與描述規(guī)范命名要遵循“動詞 名詞”的結(jié)構(gòu)例如json_formatter、text_summarizer、order_query。命名本身要能直接反映技能功能避免使用utils、helper、misc這類模糊詞匯。描述文件建議使用固定模板至少包含觸發(fā)條件、使用說明、注意事項、示例四部分。團隊內(nèi)部可以維護一份 SKILL.md 模板新成員照著填就行。示例部分容易被忽略但對模型理解非常關(guān)鍵一定要寫。9.2 上下文長度控制Skill 描述最終會注入模型上下文描述越長token 消耗越大。一個 1024 字符的 SKILL.md 大約消耗 300 到 500 token如果加載 20 個 Skill光是工具定義就可能達到上萬 token。優(yōu)化思路有三個方向一是精簡描述只保留必要信息二是按按需加載先給模型展示精簡版描述觸發(fā)后再加載完整版三是分組分類不同場景只加載對應(yīng)分組的 Skill。后兩種方案工程復(fù)雜度更高但效果明顯。9.3 安全邊界Skill 是代碼意味著它有執(zhí)行任意操作的能力。在真實項目中必須非常謹慎涉及數(shù)據(jù)庫操作、文件刪除、系統(tǒng)命令的 Skill必須顯式聲明權(quán)限級別生產(chǎn)環(huán)境禁止 Skill 直接執(zhí)行未經(jīng)確認的寫操作Skill 的輸入?yún)?shù)來自模型生成的 JSON本質(zhì)上是不可信的外部輸入要做參數(shù)校驗和長度限制所有涉及敏感操作的 Skill建議加入人工確認或二次授權(quán)機制。權(quán)限設(shè)計遵循最小原則能只讀就不要給寫權(quán)限能只操作單個資源就不要給全量權(quán)限。9.4 版本管理與發(fā)布把 Skill 當代碼來管理。每個 Skill 目錄內(nèi)建議維護一個版本號發(fā)布流程可以這樣設(shè)計開發(fā)環(huán)境直接修改源碼聯(lián)調(diào)測試測試環(huán)境加載指定版本號的 Skill 副本跑回歸用例生產(chǎn)環(huán)境發(fā)布新版本后觀察監(jiān)控指標出現(xiàn)問題立即回滾舊版本。如果團隊 Skill 數(shù)量超過幾十個建議引入專門的技能倉庫用統(tǒng)一的 CLI 工具管理 Skill 的創(chuàng)建、測試、發(fā)布和版本記錄。9.5 日志與可觀測性Agent 應(yīng)用的黑盒屬性很強必須記錄足夠多的日志才能定位問題。每次 Skill 調(diào)用至少記錄以下信息用戶輸入摘要模型決定調(diào)用的 Skill 名稱和參數(shù)Skill 執(zhí)行結(jié)果和耗時最終回復(fù)的生成情況。記錄格式建議采用結(jié)構(gòu)化 JSON方便后續(xù)分析和監(jiān)控。線上問題排查時這些日志能幫你快速還原“模型當時看到了什么、做了什么、結(jié)果是什么”的完整鏈路。10. 總結(jié)與后續(xù)學習方向Agent Skill 是 AI 大模型應(yīng)用開發(fā)中從“能調(diào)用模型”走向“能構(gòu)建 Agent 產(chǎn)品”的關(guān)鍵一環(huán)。從材料來看當前大模型應(yīng)用開發(fā)的核心競爭點正在從模型本身轉(zhuǎn)向外圍工程能力Skill 作為能力封裝的標準化單元會越來越重要。現(xiàn)在回顧一下這篇文章真正講清楚的幾個點Skill 和 Agent 的分層關(guān)系——Agent 負責決策Skill 負責執(zhí)行Skill 和 MCP 的協(xié)同關(guān)系——MCP 管連接Skill 管封裝Skill 的目錄結(jié)構(gòu)和描述文件設(shè)計一個完整的可運行的 Python 示例以及生產(chǎn)環(huán)境中的安全、版本和可觀測性要求。下一步建議你按這個順序繼續(xù)深入第一把本文的示例代碼跑通然后自己新增一個 Skill。不要復(fù)制粘貼就完事試著改一改 SKILL.md 的描述觀察模型行為的變化。第二嘗試用 Dify、FastGPT 或 Coze 這類平臺實現(xiàn)同樣的流程。平臺上的“技能”或“插件”配置底層邏輯和本文講的基本一致用平臺實現(xiàn)一遍能幫你把抽象概念具體化。第三深入研究 Agent 主循環(huán)的更多模式。本文只演示了最簡單的單輪工具調(diào)用實際產(chǎn)品往往需要多輪工具調(diào)用、反思重試、人機協(xié)同這些都是在基礎(chǔ)循環(huán)上疊加的復(fù)雜度。第四如果你在考慮 MCP可以先從一個官方或社區(qū)現(xiàn)成的 MCP Server 入手理解 MCP 的消息格式和生命周期再把 MCP 接入到自己的 Skill 體系里。畢竟 Skill 是封裝MCP 是通道兩者結(jié)合才是生產(chǎn)級方案。AI 大模型領(lǐng)域變化很快但“把復(fù)雜任務(wù)拆解成能力單元再用智能體編排它們”的思路短期內(nèi)不會過時。你現(xiàn)在花時間把 Skill 的底層機制搞清楚以后無論哪個新框架出來都能快速上手。建議收藏本文遇到概念混淆或工程問題的時候翻出來對照會比重新搜索一堆碎片資料高效得多。