1. 从一次 Agent 工具调用失败说起如果你正在搭 AI Agent大概率遇到过这种场景模型明明知道该去查数据库、该去调接口但真到执行那一步就乱了——要么参数拼错要么顺序颠倒要么干脆把工具当摆设自己编一个结果返回给你。这不是模型不够聪明而是缺少一层「怎么用工具」的规范。Agent Skill 就是来解决这个问题的。它本质是一份 Markdown 格式的提示词 SOP规定了 AI 在特定场景下的行事逻辑和处理准则。而 MCPModel Context Protocol解决的是「能不能操作外部工具」的问题。两者一个管脑子、一个管手脚配合起来才能让 Agent 真正跑通业务闭环。这篇内容面向正在搭建 AI Agent 的开发者我会把 Skill 的基础能力拆开讲清楚然后给出可复制的settings.json/config.toml骨架用 TaoToken 统一 Key 把 Skill 到 MCP 的完整链路跑通。你跟着操作能拿到一个可验证的调用结果而不是停留在概念层面。2. TaoToken 前置统一 Key 与接入地址在讲配置之前先把接入层的事情说清楚。TaoToken 在这里扮演的角色是统一入口——你不需要为每个模型、每个工具单独维护一套鉴权用一个 Key 就能覆盖对话、编码、Agent 调用等场景。官网地址https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentAPI 地址不带 UTMhttps://taotoken.net/api你需要提前准备的东西只有两样一个可用的 API Key以及确认你的 Agent 框架支持自定义 base_url。Key 在控制台的 API Keys 页面生成生成后复制保存后面配置里会用到。注意Key 只显示一次建议生成后立刻写入本地环境变量或配置文件不要硬编码在会提交到 Git 的代码里。对于长期跑编码类 Agent 的场景可以关注 Coding Plan 的额度策略如果只是验证模型对话链路用模型对话页面就能快速试通。这两条路径的入口不同后面 CTA 部分我会分开给。3. 可复制配置settings.json 与 config.toml 骨架这一节是核心。我把 Skill 定义、MCP 工具注册、统一 Key 注入三部分拆成两个配置文件你可以直接复制后改字段。3.1 Skill 文件骨架Markdown 双区结构Skill 文件本身是 Markdown分配置区和指令区。配置区定义 name 和 description指令区写规则、步骤和边界。--- name: db-query-skill description: 当用户需要查询订单、用户、库存等结构化数据时调用负责生成安全的只读 SQL 并执行 --- # 数据库查询技能 ## 描述 本技能负责将自然语言查询转换为只读 SQL并通过 MCP 数据库工具执行。 ## 使用场景 - 用户询问订单状态、用户信息、库存数量 - 需要聚合统计如某时间段订单总量 ## 指令 1. 先确认目标表名与字段不确定时调用 schema 查询工具 2. 只生成 SELECT 语句禁止 INSERT/UPDATE/DELETE 3. 拼接参数时使用占位符禁止字符串直接拼接 4. 执行前输出 SQL 供确认执行后返回前 50 行 ## 示例 输入查一下昨天创建了多少订单 输出SELECT COUNT(*) FROM orders WHERE created_at 昨天这个文件的关键在于 description 写得足够具体。模型是靠 description 判断「什么时候该加载这个 Skill」的写得太泛会导致该触发时不触发。3.2 settings.jsonMCP 工具注册与 Key 注入{ mcpServers: { db-tools: { command: npx, args: [-y, your-org/mcp-db-server], env: { DB_HOST: 127.0.0.1, DB_PORT: 5432, DB_NAME: app_prod, DB_READONLY: true } } }, agent: { baseUrl: https://taotoken.net/api, apiKeyEnv: TAOTOKEN_API_KEY, model: claude-sonnet, skillsDir: ./skills, maxToolRounds: 8 } }这里baseUrl指向 TaoToken 的 API 地址apiKeyEnv表示从环境变量读取 Key避免明文。skillsDir是 Skill 文件存放目录Agent 启动时会扫描并注册。3.3 config.toml等价写法适合 Python 系框架[llm] base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY model claude-sonnet timeout 60 [agent] skills_dir ./skills max_tool_rounds 8 [mcp.db-tools] command npx args [-y, your-org/mcp-db-server] [mcp.db-tools.env] DB_HOST 127.0.0.1 DB_PORT 5432 DB_NAME app_prod DB_READONLY true两种格式选一种即可取决于你的框架读 JSON 还是 TOML。字段含义一致不要重复配置。3.4 环境变量注入 Keyexport TAOTOKEN_API_KEYsk-你的实际KeyWindows 下用set TAOTOKEN_API_KEYsk-...或者写进.env文件由框架加载。这一步做完配置层就齐了。4. 验证请求跑通 Skill 到 MCP 的完整链路配置写完不代表能用必须做一次端到端验证。我把它拆成三个动作确认 Skill 被加载、确认 MCP 工具可调用、确认模型按 Skill 规范执行。4.1 确认 Skill 加载启动 Agent 后先发一条不涉及工具的普通消息观察日志里有没有 Skill 注册记录。正常输出类似[skill-loader] registered: db-query-skill (triggers: 订单, 用户, 库存) [skill-loader] total skills: 1如果没看到检查skillsDir路径是否正确、Markdown 文件的 front matter 是否闭合。4.2 确认 MCP 工具可调用单独测 MCP 服务不经过模型echo {jsonrpc:2.0,id:1,method:tools/list} | npx -y your-org/mcp-db-server返回里应该能看到工具列表比如query_readonly、get_schema。这一步通了说明 MCP 服务本身没问题。4.3 端到端调用验证发一条会触发 Skill 的消息帮我查一下昨天创建了多少订单预期行为链路模型识别到「订单」触发 db-query-skill → 按 Skill 指令先调 get_schema 确认字段 → 生成 SELECT 语句 → 调 query_readonly 执行 → 返回结果。成功结果类似[skill] db-query-skill activated [tool] get_schema(tableorders) - ok [tool] query_readonly(sqlSELECT COUNT(*) FROM orders WHERE created_at 2024-06-01) - 128看到skill activated和tool调用记录同时出现说明 Skill 到 MCP 的链路已经打通。如果只有 tool 调用没有 skill 激活说明 description 触发词没匹配上回去改 Skill 的 description。5. 本篇常见错排查配置和验证过程中有几个坑出现频率特别高我按现象、原因、解法列出来。5.1 Skill 不触发现象模型直接回答没有加载 Skill。原因通常是 description 写得太抽象比如只写「处理数据相关任务」。解法是把触发场景写具体包含用户可能说的关键词像「订单、用户、库存、统计」这类。5.2 MCP 工具调用报鉴权失败现象401 Unauthorized或invalid api key。先确认TAOTOKEN_API_KEY环境变量在当前 shell 里真的存在用echo $TAOTOKEN_API_KEY检查。如果是在 IDE 里跑注意 IDE 可能没继承 shell 的环境变量需要在 IDE 的终端配置里单独设置。5.3 工具调用轮次超限现象max tool rounds exceeded。说明模型在反复调工具没收敛。原因可能是 Skill 指令里没写清楚终止条件。解法是在指令区加一条「拿到结果后直接返回不要重复查询」。5.4 配置文件格式错误现象启动直接报解析错误。JSON 不支持注释TOML 对缩进敏感。建议用python -m json.tool settings.json或toml库校验一遍再启动。5.5 Skill 与 MCP 职责混淆现象把业务规则写进了 MCP 服务里导致工具变得很重。记住分工MCP 只管「能不能操作」Skill 管「按什么流程操作」。业务规则、边界条件、输出格式都应该放在 Skill 里。6. 把链路固定下来再谈扩展跑通一次之后建议把验证动作固化成脚本每次改配置后自动跑一遍。这样后面加新 Skill、接新 MCP 工具时不会因为一处改动把整条链路弄挂。如果你卡在接入环节优先去看 API Keys 和接入文档把 Key 和 base_url 这两件事确认死如果只是想先验证模型对话是否正常用模型对话页面发一条消息最快如果是长期跑编码类 Agent、需要稳定额度Coding Plan 的路径更适合你。Skill 和 MCP 的关系说到底就是「脑」和「手」的关系。手再多没有脑定规矩Agent 还是乱来。先把一个 Skill 写扎实比堆十个半成品有用得多。
