MCP 负责“能做什么”，Agent Skills 负责“应该怎么做”：用 SKILL.md 与 config.toml 搭出 2026 年 Agent 分层骨架

1. 为什么 2026 年还在把 MCP 和 Skills 混着用MCP 负责“能做什么”Agent Skills 负责“应该怎么做”这句话在 2026 年已经成了 Agent 架构分层的默认共识。但我在实际项目里看到的情况是很多人把两者塞进同一个配置文件里结果工具调用能跑通执行策略却完全失控。MCP 是工具层它把数据库、文件系统、HTTP API、浏览器这些外部资源统一成标准接口解决的是 Agent 能摸到多大世界的问题。Agent Skills 是知识层它用 SKILL.md 把某个领域的操作流程、判断标准、输出格式封装成可复用的能力包解决的是 Agent 在那个世界里干得专不专业的问题。我试过把同一份操作手册分别喂给两个 Agent 客户端一个按步骤把任务跑得干干净净另一个把关键步骤跳过去直接开始瞎编。两个客户端用的是同一个模型连温度参数都一样唯一的区别就是其中一份说明书被写成了标准 SKILL.md 格式另一份只是塞在对话里的普通文本。这个对比让我第一次真切感受到Agent 时代的竞争已经从模型本身转移到了怎么给模型写操作手册。这篇文章要交付的东西很具体一套可复制的 config.toml 与 SKILL.md 骨架CC Switch 和 Cline 的配置片段以及分层调用与报错排查的验证动作。场景是本地 AI 工具接入 TaoToken 统一 Key/API 通道让 MCP 工具层和 Skills 知识层各走各的通道互不干扰。如果你正在搭 2026 年的 Agent 分层骨架这篇可以直接跟着做。2. 前置准备TaoToken 统一 Key 与 API 通道在写 config.toml 之前先把通道打通。TaoToken 在这里扮演的角色是统一 Key/API 通道让本地 AI 工具CC Switch、Cline、Claude Code 等通过一个入口访问模型能力而 MCP 工具层和 Skills 知识层各自独立配置不互相污染。你需要先拿到 API Key。访问控制台创建 Key地址是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。创建时建议按用途分 Key比如一个给 MCP 工具调用一个给 Skills 执行策略方便后续排查问题时定位是哪一层出的错。API 基础地址是 https://taotoken.net/api 注意这个地址不带 UTM 参数直接写进配置文件即可。模型对话入口在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 你可以先在那里验证 Key 是否可用再写进本地配置。注意MCP 工具层和 Skills 知识层建议使用不同的 Key 或至少不同的配置段这样当出现 401 或 429 时你能快速判断是工具调用超限还是技能执行超限。前置准备清单如下项目值用途API Basehttps://taotoken.net/api所有请求的基础地址API Key控制台创建鉴权模型对话验证https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite确认 Key 可用接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite查参数与错误码Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite长期编码/Agent 场景3. 可复制配置config.toml 与 SKILL.md 骨架3.1 config.toml 分层骨架下面这份 config.toml 把 MCP 工具层和 Skills 知识层分开配置。MCP 段负责工具连接Skills 段负责技能加载路径和执行策略。你可以直接复制把 api_key 换成自己的。# ~/.config/agent/config.toml # 2026 Agent 分层骨架MCP 工具层 Skills 知识层 [provider] name taotoken api_base https://taotoken.net/api api_key sk-your-key-here default_model claude-sonnet-4-20250514 # MCP 工具层负责“能做什么” [mcp] enabled true progressive_discovery true # 2026-07-28 协议更新后的渐进式发现 servers [ { name filesystem, command npx, args [-y, modelcontextprotocol/server-filesystem, /workspace] }, { name fetch, command npx, args [-y, modelcontextprotocol/server-fetch] } ] # Skills 知识层负责“应该怎么做” [skills] enabled true skill_dirs [~/.config/agent/skills] auto_load true max_skills 32 description_window 57 # 索引窗口字符数触发条件必须写进前 57 字符 # 分层调用策略 [routing] tool_layer mcp # 工具调用走 MCP knowledge_layer skills # 执行策略走 Skills fallback_to_prompt false # 禁止回退到裸 prompt避免策略漂移这份配置的关键点在[routing]段。tool_layer和knowledge_layer分开指定意味着当 Agent 需要调用工具时走 MCP 通道需要判断执行策略时走 Skills 通道。fallback_to_prompt false是防止技能加载失败时偷偷回退到裸 prompt那样会让执行策略悄悄漂移你根本不知道是哪一层出的问题。3.2 SKILL.md 标准骨架SKILL.md 由 YAML 元数据区和 Markdown 正文区组成。YAML 区告诉 Agent 这个技能叫什么、什么时候该用正文区才是真正的操作手册。下面是一个可直接改写的骨架--- name: repo-file-finder description: 在大型代码仓库里按语义定位文件。当用户需要找某个功能、某个报错、某个配置对应的源码文件时使用。不适用于已经明确给出文件路径的提问。 version: 1.0.0 --- # 任务目标 根据用户描述的功能或报错定位仓库中对应的源码文件给出相对路径和一句话说明。 # 执行步骤 1. 先用 grep 搜索关键词找到候选文件列表。 2. 对候选文件逐个读取开头 50 行判断职责是否匹配。 3. 匹配结果按相关度排序输出相对路径和职责说明。 4. 找不到匹配时明确回答未找到不编造路径。 # 输出格式 每行一个文件相对路径 | 职责一句话 | 匹配关键词 # 质量标准 - 路径必须是仓库内真实存在的相对路径 - 未找到时必须如实说明禁止猜测 - 每次最多输出 5 个候选避免信息过载description 这一行是全套规范里最讲究的字段。它决定了 Agent 在什么情况下会主动加载这个技能。写法要包含触发条件和排除条件前半句说什么时候该用后半句说什么时候不该用。平台索引技能时只显示简介的开头部分大概 57 个字符的窗口所以触发场景必须压进开头一句话。3.3 CC Switch 配置片段CC Switch 用来在多个模型通道之间切换。把 TaoToken 配成一个通道MCP 和 Skills 共用这个通道但走不同的 Key{ providers: [ { name: taotoken-mcp, api_base: https://taotoken.net/api, api_key: sk-mcp-key, models: [claude-sonnet-4-20250514], tags: [mcp, tool-layer] }, { name: taotoken-skills, api_base: https://taotoken.net/api, api_key: sk-skills-key, models: [claude-sonnet-4-20250514], tags: [skills, knowledge-layer] } ], active: taotoken-mcp }3.4 Cline 配置片段Cline 的配置在 settings.json 里重点是把 MCP 服务器和 Skills 目录分开声明{ cline.apiProvider: openai, cline.openAiBaseUrl: https://taotoken.net/api, cline.openAiApiKey: sk-your-key-here, cline.model: claude-sonnet-4-20250514, cline.mcpServers: { filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, /workspace] } }, cline.skillsDir: ~/.config/agent/skills, cline.skillsAutoLoad: true }4. 验证请求与成功结果配置写完之后分三步验证。第一步验证通道第二步验证 MCP 工具层第三步验证 Skills 知识层。4.1 验证 API 通道用 curl 直接打 TaoToken 的 API确认 Key 和 Base 地址正确curl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: sk-your-key-here \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK}] }成功结果会返回一个 JSONcontent 数组里包含模型回复。如果返回 401检查 Key 是否复制完整如果返回 404检查 api_base 是否写成了 https://taotoken.net/api 而不是带路径的地址。4.2 验证 MCP 工具层启动 MCP 服务器确认工具列表能被拉取npx -y modelcontextprotocol/server-filesystem /workspace --list-tools成功时会输出工具定义列表包含 read_file、write_file、list_directory 等。如果这一步失败说明 MCP 工具层没通跟 Skills 无关先排查 MCP 服务器本身。4.3 验证 Skills 知识层在 Agent 对话里发一个能触发技能的任务观察它是否加载了 SKILL.md帮我在 /workspace 里找一下处理用户登录逻辑的文件成功结果应该看到 Agent 先加载 repo-file-finder 技能然后按 SKILL.md 里的步骤执行grep 搜索、读取候选文件、按相关度排序输出。如果 Agent 直接开始瞎猜路径说明技能没被加载检查 skill_dirs 路径和 description 的触发条件。提示验证模型本身是否正常可以去 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 直接对话排除是模型问题还是配置问题。5. 本篇常见错排查5.1 技能不触发description 被截断最常见的错误是 description 写得太长触发条件写在末尾结果被 57 字符索引窗口截断Agent 根本看不到。排查方法是把 description 的前 57 个字符单独拿出来读一遍问自己如果我是个对项目一无所知的 Agent看到这句话会不会知道什么时候该用这个技能。如果答案是否定的就把触发场景往前挪。5.2 工具调用报 429MCP 和 Skills 共用 Key如果 MCP 工具层和 Skills 知识层共用同一个 Key工具调用频繁时可能触发限流导致技能加载也失败。排查方法是看错误码429 说明限流401 说明鉴权失败。解决方式是给两层分配不同的 Key在 config.toml 的 provider 段和 mcp 段分别指定。5.3 技能加载了但执行策略漂移如果 Agent 加载了 SKILL.md 但执行时跳过了关键步骤检查fallback_to_prompt是否被设成了 true。这个配置项一旦为 true技能加载失败时会偷偷回退到裸 prompt执行策略就会漂移。把它设成 false让失败显式暴露出来。5.4 MCP 服务器启动失败npx 缓存问题MCP 服务器用 npx 启动时如果本地缓存损坏会出现启动超时。排查方法是手动跑一次 npx 命令看是否有报错。解决方式是清理 npx 缓存后重试或者把 MCP 服务器装到本地 node_modules 里用绝对路径启动。5.5 技能目录路径不生效skill_dirs 里用了~符号但某些客户端不展开波浪号。排查方法是把路径写成绝对路径比如/home/username/.config/agent/skills。改完之后重启客户端再发一个触发任务验证。5.6 渐进式发现没生效2026-07-28 协议更新后支持渐进式发现但需要客户端和服务器都开启。检查 config.toml 里progressive_discovery true是否设置以及 MCP 服务器版本是否支持。如果服务器不支持客户端会回退到一次性加载全部工具定义上下文会被撑大。6. 分层调用的长期维护与 CTA分层骨架搭好之后维护的重点是技能库的版本管理和入口治理。给技能目录初始化 git 仓库每次改动都提交技能文件跟代码一样有完整的变更历史。规定技能必须包含 name、description、清晰的步骤和验收标准description 必须写明触发条件和排除条件。这个入口规范能挡住大部分质量低下的技能比事后审查高效得多。如果你在长期编码或 Agent 场景里需要稳定的通道可以看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite 。接入文档和错误码查询在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。API Key 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite 。模型对话验证在 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。今晚就能做的三件事把你最近一个月重复做过三次以上的手工任务列出来挑一个写成一版最小的 SKILL.md跑一遍真实任务验证它是否被正确加载和执行把 description 的写法当成头等大事来打磨写完先自己读一遍开头 57 个字符给你的技能目录初始化 git 仓库哪怕只有你一个人用。版本历史是技能质量的保险丝等技能数量超过十个你会发现没有版本管理的技能库根本不敢改。