1. 从“只会聊天”到“真能干活”Agent Skill 到底解决了什么问题你可能遇到过这种场景问模型“帮我查一下北京现在的天气”它回你一句“我无法获取实时信息”。不是模型不聪明而是它天生只能“动口”不能“动手”。Agent Skill 就是给模型装上手脚的那层封装——把查天气、读文件、发请求、写数据库这些具体动作打包成模型能看懂、能调用的标准化模块。一句话定义Agent Skill 是把一项具体能力封装成带名称、描述、参数 Schema 和执行函数的模块让 Agent 在需要时自动调用。它在不同框架里叫法不同OpenAI 体系里叫 Function Calling 的 functionLangChain 里叫 ToolMCP 里叫 ToolCoze 里叫插件本质是一回事。适合谁看已经会用 Python 调模型接口、想让自己的 Agent 从“陪聊”升级到“办事”的开发者正在选型 Function Calling 还是 MCP 的工程同学以及想搞明白 Skill 和 MCP 到底啥关系的技术负责人。我试过把一个“查汇率”的 Skill 塞进客服 Agent原本需要人工转接的汇率咨询直接由模型调接口返回响应从分钟级降到秒级。关键不在于代码多复杂而在于把“什么时候调、传什么参数、返回什么”这三件事描述清楚。这篇会带你走完整条链路先讲清 Skill 的运行原理Function Calling 循环再用 Python 手写一个可复用的 Skill 骨架接着把它注册成 MCP 工具最后通过 TaoToken 统一 Key 通道完成一次端到端调用验证。全程可复制跑通为止。需要提前说明的是Skill 的开发核心不是写多花哨的函数而是写好那段给模型看的 JSON Schema 描述。描述写得准模型选对 Skill 的概率就高描述含糊模型要么不调要么传错参数。这是后面所有实战的地基。2. TaoToken 统一 Key 接入为什么 Agent 项目需要一个稳定通道做 Agent 开发的人很快会撞上一个现实问题Skill 要调模型模型接口要 Key而不同模型、不同环境、不同同事之间的 Key 管理一团乱。本地调试用一个 Key测试环境换一个上线再换一个代码里硬编码的 Base URL 改来改去稍不注意就把测试 Key 提交进了仓库。TaoToken 在这里扮演的角色是统一入口一个 Key、一个 Base URL兼容 OpenAI 风格的接口协议。你的 Agent 代码里OpenAI(api_key..., base_url...)这两行配置一次写好后面换模型、换环境只需要改 Model ID不用动调用逻辑。对 Skill 开发来说这意味着你可以把精力放在 Skill 本身的描述和执行函数上而不是反复折腾接入层。它的接口地址是https://taotoken.net/api兼容 OpenAI 的/v1/chat/completions路径。也就是说你原来用openai这个 Python 包写的代码只需要把base_url指过来其余client.chat.completions.create(...)的写法完全不变。这对已经写过 Function Calling 代码的人来说迁移成本几乎为零。为什么 Agent 场景特别需要这种统一通道因为 Agent 的运行循环里一次用户请求可能触发多轮模型调用第一轮模型决定调哪个 Skill执行完 Skill 后把结果送回模型模型再决定是继续调下一个 Skill 还是生成最终回复。这个循环里每一次模型调用都要走同一个通道如果通道不稳定或者 Key 频繁失效整个 Agent 就卡住了。统一 Key 的价值在于让这个循环的每一环都指向同一个可靠入口。另外Skill 开发阶段经常需要对比不同模型对同一段 Schema 描述的理解能力。有的模型对参数类型判断更准有的模型在长上下文里更稳。用统一通道的好处是切换模型只改一个字符串你可以快速做 A/B 对比找出最适合你 Skill 集合的那个 Model ID。配置上你只需要准备三样东西Base URL 填https://taotoken.net/apiAPI Key 从控制台生成Model ID 按你实际要用的模型填。这三件套在后面的 JSON 配置和 Python 代码里会反复出现先记牢。控制台入口在https://taotoken.net/consoleAPI Key 管理在https://taotoken.net/api-keys接入文档在https://taotoken.net/doc需要的话可以对照着看。3. 可复制配置Skill 骨架 MCP 注册 TaoToken 三件套这一节直接给可复制的代码和配置。先看 TaoToken 的三件套怎么落到配置文件里再写 Skill 骨架最后把它注册成 MCP 工具。先建一个config.json把接入信息集中管理避免硬编码散落各处{ base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, model_id: gpt-4o-mini, timeout: 30 }注意base_url只写到/api不要自己拼/v1SDK 会按 OpenAI 规范补全路径。model_id按你控制台里实际可用的模型填这里用gpt-4o-mini举例。接着写 Skill 骨架。一个 Skill 由三部分组成名称与描述、参数 Schema、执行函数。下面这个get_weather是完整可跑的示例import json import requests from openai import OpenAI with open(config.json, r, encodingutf-8) as f: cfg json.load(f) client OpenAI( api_keycfg[api_key], base_urlcfg[base_url], timeoutcfg[timeout], ) def get_weather(city: str) - str: 查询指定城市的实时天气返回温度和天气状况。 url https://api.open-meteo.com/v1/forecast params { latitude: 39.9042, longitude: 116.4074, current_weather: True, } try: resp requests.get(url, paramsparams, timeout10) data resp.json() temp data[current_weather][temperature] wind data[current_weather][windspeed] return f{city} 当前温度 {temp}°C风速 {wind} km/h except Exception as e: return f查询天气失败{str(e)} weather_tool { type: function, function: { name: get_weather, description: 获取指定城市的实时天气。当用户询问某地天气、温度、是否下雨时使用。, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如 Beijing、Shanghai, } }, required: [city], }, }, } available_functions {get_weather: get_weather}这段代码里最关键的是description字段。它直接决定模型什么时候会选这个 Skill。写法上要包含“做什么”和“什么时候用”比如“当用户询问某地天气时使用”这样模型在收到“北京热不热”这种口语化输入时也能正确匹配。如果你要把这个 Skill 注册成 MCP 工具让支持 MCP 的客户端也能发现它可以用mcp这个 Python 包写一个最小服务器。先装依赖pip install mcp openai requests然后写weather_server.pyfrom mcp.server import Server from mcp.server.stdio import stdio_server from mcp.types import Tool, TextContent import asyncio import requests app Server(weather-skill) app.list_tools() async def list_tools(): return [ Tool( nameget_weather, description获取指定城市的实时天气。当用户询问某地天气时使用。, inputSchema{ type: object, properties: { city: {type: string, description: 城市名称} }, required: [city], }, ) ] app.call_tool() async def call_tool(name: str, arguments: dict): if name get_weather: city arguments.get(city, Beijing) url https://api.open-meteo.com/v1/forecast params {latitude: 39.9042, longitude: 116.4074, current_weather: True} resp requests.get(url, paramsparams, timeout10) data resp.json() temp data[current_weather][temperature] return [TextContent(typetext, textf{city} 当前温度 {temp}°C)] raise ValueError(f未知工具{name}) async def main(): async with stdio_server() as (read, write): await app.run(read, write, app.create_initialization_options()) if __name__ __main__: asyncio.run(main())这个 MCP 服务器通过 stdio 暴露get_weather工具任何支持 MCP 的客户端连上后都能自动发现它。注意inputSchema的结构和前面 Function Calling 的parameters完全一致这就是 Skill 描述在不同协议间的可迁移性。如果你用的是 Claude Code 这类支持 MCP 的编码工具可以在它的配置里挂载这个服务器。以 Claude Code 的 MCP 配置为例在项目根目录的.mcp.json里写{ mcpServers: { weather-skill: { command: python, args: [weather_server.py], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的TaoToken密钥 } } } }这里把 TaoToken 的 Base URL 和 Key 通过环境变量传给 MCP 服务器服务器内部如果要调模型读这两个变量即可。三件套Base URL、Key、Model ID在 MCP 场景下同样适用只是传递方式从 JSON 配置变成了环境变量。4. 端到端验证一次请求跑通 Skill 调用循环配置写完现在跑一次完整验证。目标是用户输入一句自然语言模型自动决定调用get_weather执行函数拿到结果模型再生成最终回复。先写运行循环def run_agent(user_message: str, tools: list, functions: dict) - str: messages [{role: user, content: user_message}] response client.chat.completions.create( modelcfg[model_id], messagesmessages, toolstools, tool_choiceauto, ) msg response.choices[0].message while msg.tool_calls: messages.append(msg) for tc in msg.tool_calls: fn_name tc.function.name fn_args json.loads(tc.function.arguments) result functions[fn_name](**fn_args) messages.append({ role: tool, tool_call_id: tc.id, content: str(result), }) response client.chat.completions.create( modelcfg[model_id], messagesmessages, toolstools, tool_choiceauto, ) msg response.choices[0].message return msg.content if __name__ __main__: print(run_agent(北京现在天气怎么样, [weather_tool], available_functions))运行python agent.py你会看到类似这样的输出北京 当前温度 18.3°C风速 12.5 km/h如果模型在最终回复里做了自然语言润色可能输出“北京现在气温大约 18.3 摄氏度风速 12.5 公里每小时天气比较舒适”。无论哪种都说明整条链路通了模型识别意图 → 输出 tool_calls → 本地执行函数 → 结果回传 → 模型生成回复。验证成功的几个标志第一response.choices[0].message.tool_calls不为空说明模型确实决定调用 Skill第二tc.function.arguments里能解析出{city: Beijing}说明参数 Schema 被正确理解第三最终msg.content是自然语言而非空值说明结果回传后模型完成了二次推理。如果你想验证 MCP 那条链路可以用 MCP 客户端连上weather_server.py调用list_tools应该返回get_weather的定义调用call_tool传入{city: Shanghai}应该返回温度文本。这一步通了说明你的 Skill 不仅能被自家 Agent 用还能被任何 MCP 客户端发现和调用。实测下来最容易出问题的不是函数逻辑而是模型没触发 tool_calls。这时候先检查tool_choice是不是auto再检查description里有没有写清使用场景。如果模型把“北京天气”理解成闲聊而不是查询多半是描述里缺了“当用户询问天气时使用”这类触发条件。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错逐个拆。这些错误在 Skill 开发和 MCP 接入过程中出现频率最高提前知道怎么定位能省很多时间。401 Unauthorized最常见的原因是 Key 没传对或者 Base URL 写错。先确认config.json里的api_key是完整的sk-开头字符串没有多余空格。再确认base_url是https://taotoken.net/api不要写成https://taotoken.net/api/v1或者漏掉/api。如果用的是环境变量检查变量名拼写和加载顺序。401 的本质是认证失败跟 Skill 逻辑无关先把接入层排干净。local proxy failed / connection refused这个报错通常出现在 MCP 服务器启动阶段。如果你在.mcp.json里配的command是python但系统里 Python 不在 PATH 上客户端就拉不起服务器。解决办法是写绝对路径比如/usr/bin/python3或者虚拟环境里的./venv/bin/python。另外args里的脚本路径要相对于客户端的工作目录不确定的话也写绝对路径。这个错误跟网络代理无关纯粹是进程启动失败。reading choices of undefined这个报错说明response.choices是 undefined也就是模型接口返回的结构不符合预期。常见原因有三个一是 Base URL 指错了请求打到了非 OpenAI 兼容的端点二是 Model ID 填了一个不存在的模型接口返回了错误对象而不是标准响应三是请求体里messages格式不对比如 role 写成了user 带空格。排查方法是把response整个打印出来看返回的 JSON 里有没有error字段。如果是{error: {message: model not found}}那就是 Model ID 的问题。OAuth 相关报错如果你在 Claude Code 或类似工具里看到 OAuth 失败通常是因为工具默认走官方登录流程而你想用 TaoToken 的 Key 通道。这时候需要在工具的配置里显式指定 Base URL 和 API Key覆盖默认的 OAuth 路径。以 Claude Code 为例可以在settings.json里配置{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }注意这里的变量名是工具约定的不同工具可能不同。核心思路是只要工具支持自定义 Base URL 和 Key就能走统一通道绕开 OAuth。如果工具不支持那就只能用它默认的接入方式。还有一个容易忽略的坑MCP 服务器通过 stdio 通信时如果服务器往 stdout 打印了调试信息会污染协议数据导致客户端解析失败。所以weather_server.py里不要用print输出日志要输出就用sys.stderr。这个错误不会报得很明确通常表现为客户端连上了但list_tools返回空或者超时。6. 把 Skill 用起来从单个示例到你的 Agent 能力矩阵跑通一个get_weather只是起点。真正让 Agent 有超能力的是把多个 Skill 组合起来形成能力矩阵。比如一个“出行助手”Agent可以同时挂载查天气、查航班、查汇率、发邮件四个 Skill模型会根据用户意图自动选择调用哪个或哪几个。组合的关键在于 Skill 描述的边界要清晰。如果两个 Skill 的描述都写了“查询信息”模型就不知道该选哪个。正确做法是让每个 Skill 的描述互斥且具体get_weather写“查询城市天气”get_flight写“查询航班状态”get_exchange_rate写“查询货币汇率”。描述越具体模型路由越准。另一个实践技巧是把 Skill 的返回结果结构化。比如get_weather不要只返回一句自然语言而是返回 JSON 字符串让模型自己决定怎么呈现给用户。这样同一个 Skill 可以适配不同的输出风格要求复用性更强。如果你要把 Skill 分享给团队或社区MCP 是更好的交付形式。把 Skill 封装成 MCP 服务器后任何人只要在客户端配置里挂上你的服务器地址就能直接使用不需要复制代码。这也是 MCP 作为“管道”的价值Skill 是内容MCP 是分发标准。最后给一个实用建议每写一个新 Skill先用单元测试验证执行函数本身正确再放进 Agent 循环里测模型调用。因为模型有时会传入你意想不到的参数比如把city传成北京 带空格或者传成Beijing, China。执行函数里做好参数清洗和异常捕获比在模型侧反复调描述更省事。需要对照接入细节的话接入文档在https://taotoken.net/docAPI Key 在https://taotoken.net/api-keys管理模型对话调试可以用https://taotoken.net/chat长期跑编码类 Agent 任务可以看 Coding Plan 的说明。三件套配好剩下的就是构思你的 Agent 该有哪些 Skill然后一个一个实现。