AI Agent 的能力上限并不取决于模型本身的参数量而取决于它能否调用外部工具、获取实时数据、按固定流程完成多步骤任务。在实际工程里为 Agent 扩展能力有两条主流路径MCP 和 Skill。MCPModel Context Protocol负责解决“Agent 如何标准、安全地连接外部工具和数据源”Skill 负责解决“Agent 如何按照高质量提示流程完成某一类任务”。这两条路径经常被混在一起讲实战中却各自有独立的坑MCP Server 写好了客户端不加载Skill 目录放对了模型却不执行。这篇文章会从核心概念、环境准备、最小实现、选型对比、排查链路和生产建议六个层面把 MCP 与 Skill 的深度应用完整过一遍适合正在学习 AI Agent 开发、准备搭建工具型 Agent 的读者。1. 先理解 MCP 和 Skill 在 Agent 体系里的不同角色1.1 MCP 是什么为什么 Agent 需要它MCP 是一套模型上下文协议由 Anthropic 在 2024 年底开源目的是把“模型如何调用工具”这件事标准化。在没有 MCP 之前每个 Agent 产品都要自己定义一套工具调用格式第三方工具要接入不同的 Agent 就得各写一套适配层。工具方接入 A 产品写一套接口接入 B 产品再写一套接口维护成本非常高。MCP 出现之后工具提供方只需要实现一个 MCP Server任何支持 MCP 的客户端都可以复用同一套协议来发现和调用这些工具。MCP 的架构涉及四个核心角色MCP ClientAgent 应用一侧负责发起工具发现和工具调用请求。MCP Server工具和数据源一侧负责把真实能力封装成标准接口。传输层本地场景通常使用 stdio远程场景使用 HTTP 或 SSE。原语Tools工具、Resources资源、Prompts提示模板。用一个通俗类比MCP 相当于给 Agent 生态统一了一套标准接口。Agent 是主机外部工具是外设接口统一之后外设可以即插即用。社区里已经能看到大量真实案例例如用 Playwright MCP 做浏览器自动化用 MCP 连接蓝湖、MasterGo 这类设计协作平台用 Blender MCP 控制三维软件用 Unity MCP、Cocos Creator MCP 做游戏引擎对接。它们暴露的能力不同但接入方式高度一致这正是协议标准化的价值。1.2 Skill 是什么它和 MCP 的核心差异是什么Skill 在 Claude 等 Agent 产品中是一种文件形态的指令包。它通常是一个文件夹里面放一份 SKILL.md 和若干脚本、参考资料。SKILL.md 使用 Markdown 描述一个任务的完整执行流程模型在对话中命中 Skill 描述的场景时会把 SKILL.md 的内容作为上下文注入再按照里面的流程分步骤执行。MCP 和 Skill 最核心的差异是MCP 偏重能力接入。它解决的是“模型能不能调一个外部函数、能不能读一份外部数据”。Skill 偏重流程与知识注入。它解决的是“模型知不知道按什么顺序干活、按什么标准判断结果”。举例来说MCP 可以暴露一个“查询订单状态”的工具但模型可能不知道什么时候该查、查完之后怎么回复。Skill 则在流程里写明先确认订单号格式再调用订单查询工具然后根据状态给出对应话术。两者解决的并不是同一个问题。1.3 两者应该配合而不是二选一一个生产级 Agent 通常同时具备 MCP 和 Skill。Skill 负责流程编排和判断标准MCP 负责真正执行工具调用。典型场景是电商客服 AgentSkill 定义“订单核查标准流程”流程里要求查询订单状态和计算运费这两个动作就调用 MCP 暴露的订单工具。理解这个分工之后再去看各种教程里的案例就不会混乱。凡是看到“给 Agent 加数据库查询能力”“给 Agent 加浏览器操作能力”大概率是在讲 MCP凡是看到“代码审查 Skill”“数学建模 Skill”“写作润色 Skill”大概率是在讲流程和提示词工程。2. 环境准备把 Agent 客户端、Python 和 MCP SDK 先跑通2.1 需要准备哪些工具在动手写代码之前先确认本机环境。学习环境尽量简单不需要搭建服务器MCP Server 以本地进程方式运行即可。准备清单如下工具作用版本建议Agent 客户端作为 MCP Client 和 Skill 的宿主Claude 系列或兼容 MCP/Skill 的客户端最新稳定版Python编写和运行 MCP Server3.9 及以上uv 或 pip管理 Python 依赖任选其一Node.js部分 MCP SDK 和官方 Server 需要18 及以上如果使用 Claude Code可以通过命令行直接管理 MCP Server。Claude Desktop 则通过配置文件加载。原始材料没有给出固定版本落地前要先确认自己使用的客户端版本和协议版本是否匹配。2.2 创建项目目录和独立虚拟环境项目目录建议按用途拆分MCP 代码和 Skill 文件分开存放mkdir -p ~/agent-demo/mcp ~/agent-demo/skills cd ~/agent-demo python -m venv .venv source .venv/bin/activate pip install -U mcp[cli]如果使用 uv可以更简洁uv init agent-demo cd agent-demo uv add mcp[cli]这里使用虚拟环境的目的是隔离依赖。MCP Server 会作为独立进程被客户端拉起如果依赖装到了全局环境换一台机器或者换一个 Python 版本时很容易出现环境不一致导致 Server 启动失败。2.3 验证安装结果安装完成后先做一次快速验证python -c import mcp; print(mcp.__version__)再验证客户端状态claude --version claude mcp listclaude mcp list初始会显示空列表或默认配置这证明客户端已经支持 MCP 管理命令。如果这一步就报错常见原因是命令没有加入 PATH或者客户端版本过旧。注意环境验证这一步不要跳过。MCP Server 最常见的启动失败原因就是虚拟环境没有激活或客户端通过系统 Python 找不到 mcp 包。3. 从零实现一个最小 MCP Server3.1 项目结构和文件划分在一个最小项目中MCP 部分只需要一个 Python 文件agent-demo/ ├── .venv/ ├── mcp/ │ └── order_server.py └── skills/ └── code-review/ ├── SKILL.md ├── scripts/ └── references/先看 mcp 目录。这个 Server 只暴露两个工具查询订单状态、计算运费。工具本身逻辑很简单但已经足够说明注册、调用、调试的完整过程。3.2 用 FastMCP 声明两个工具FastMCP 是官方 Python SDK 提供的高层封装适合快速开发。完整代码如下from mcp.server.fastmcp import FastMCP mcp FastMCP(order-query-server) mcp.tool() def query_order_status(order_no: str) - str: 根据订单号查询订单状态。 Args: order_no: 订单号例如 ORD20250101001 # 实际项目中这里会查询订单数据库或调用内部接口 return f订单 {order_no} 当前状态为待发货 mcp.tool() def calc_shipping_fee(weight_kg: float, city: str) - str: 根据包裹重量和目的城市计算运费。 Args: weight_kg: 包裹重量单位千克 city: 目的城市名称 base 8.0 extra max(0, weight_kg - 1) * 2.0 return f到 {city} 的运费为 {base extra:.2f} 元 if __name__ __main__: mcp.run()这段代码有三个关键点mcp.tool()装饰器把普通函数注册为 MCP 工具。函数 docstring 必须认真写。模型会读取 docstring 来判断这个工具做什么、参数是什么含义。docstring 写得模糊模型就可能在该调用时不调用。返回结果统一使用字符串。MCP 工具调用的返回值最终要作为文本上下文交给模型结构化数据可以先转成 JSON 字符串再返回。3.3 在客户端里注册 MCP ServerMCP Server 默认使用 stdio 传输。这意味着客户端会以子进程方式启动order_server.py通过标准输入输出与它通信。因此 Server 代码里不要出现额外的print()任何输出到 stdout 的内容都会污染协议通信。在 Claude Code 中注册命令如下claude mcp add order-query -- python /Users/你的用户名/agent-demo/mcp/order_server.py在 Claude Desktop 中需要编辑配置文件路径通常是claude_desktop_config.json{ mcpServers: { order-query: { command: python, args: [/Users/你的用户名/agent-demo/mcp/order_server.py] } } }注意两个容易出错的地方command写python时客户端会使用系统默认 Python而不是项目虚拟环境里的 Python。如果虚拟环境里装了 mcp 而系统环境没装就会启动失败。推荐在开发阶段直接写虚拟环境内 python 的绝对路径。args数组中必须使用绝对路径。相对路径会以客户端的工作目录为基准启动位置不同就会找不到文件。3.4 运行验证确认工具能被模型看到注册完成后先查看注册状态claude mcp list正常输出会列出order-query以及它暴露的工具。接着在对话中提问查询订单 ORD20250101001 的状态 计算一个 3.5 千克的包裹发往上海的运费模型应当调用对应工具并返回结果。如果没有触发可以强制提示“使用 order-query 提供的工具查询。”一旦验证通过这套链路就可以扩展。真实项目里把函数内部改成查询数据库、调用内部 HTTP 接口、操作 Redis 缓存MCP Server 的骨架不需要变。4. Skill 的落地方式从 SKILL.md 到完整指令包4.1 Skill 的标准目录结构Skill 不需要编译也不需要独立进程它就是一个有固定结构的目录skills/ └── code-review/ ├── SKILL.md ├── scripts/ │ └── check_secrets.py └── references/ └── security-checklist.md其中SKILL.md是入口文件必须存在。scripts/放可执行脚本references/放参考资料。目录名就是 Skill 名称同一个目录下不要放两份 SKILL.md。4.2 写一份可被模型识别的 SKILL.mdSKILL.md 分为两部分YAML frontmatter 和正文。frontmatter 里的name和description是模型判断是否使用该 Skill 的依据。--- name: code-review description: 对 Python 后端代码进行代码审查重点检查安全问题、异常处理和日志规范。当用户要求审查代码、检查代码风险或 review 分支时使用。 --- # 代码审查流程 当你收到一段 Python 代码时按以下步骤执行审查 1. 先阅读代码的输入、处理和输出路径。 2. 检查是否存在裸 except是否吞掉了异常。 3. 检查数据库查询是否缺少参数校验。 4. 检查日志中是否输出密码、Token、手机号等敏感信息。 5. 输出审查结论按 严重 / 建议 / 提示 三级分类。 ## 输出格式 - 严重问题必须修复 - 建议问题推荐修复 - 提示问题属于改进空间这里最关键的是description。它必须说明两个信息这个 Skill 在什么场景下使用以及什么用户请求会触发它。如果 description 写得太泛例如只写“用于代码审查”模型可能在用户要求其他类型的文字检查时误触发也可能在用户要求代码审查时没触发。4.3 在 Skill 中加入脚本和参考资料有些 Skill 不只是指导模型按流程思考还需要执行具体计算或完整性校验。这时可以在 SKILL.md 中引用 scripts 目录里的脚本。例如scripts/check_secrets.py可以扫描代码片段中是否包含疑似密钥的字符串。SKILL.md 中可以这样写## 辅助脚本 如果代码中包含赋值表达式使用以下命令检查密钥泄露 bash python scripts/check_secrets.py /path/to/filereferences/ 目录适合放置静态资料例如安全规范清单、命名规范、字段字典。模型可以按需读取不需要一次性塞进上下文。这比把大量规范直接写进 SKILL.md 正文更节省上下文空间。 注意SKILL.md 内引用资源时尽量使用相对路径。Skill 目录可能被移动到不同的 Agent 工程中绝对路径会导致引用失效。 ### 4.4 测试 Skill 是否真正生效 Skill 的测试方法和代码测试不同重点验证模型是否真的按流程执行。 测试步骤可以这样安排 - 准备一份包含安全问题的 Python 代码片段。 - 在对话中提问“帮我 review 这段代码检查有没有风险。” - 观察模型是否先分解输入、输出路径是否引用了 Skill 里的检查项是否输出三级分类结论。 - 如果模型直接给出一段泛泛而谈的代码评价说明 Skill 没有被触发或 description 中没有命中用户意图。 更直接的验证方式是显式指定 Skill 名称“使用 code-review Skill 审查下面这段代码。”能按流程执行说明 Skill 本身没问题不能执行就要检查文件位置和 frontmatter 格式。 ## 5. MCP 与 Skill 的选型对比什么场景用哪一个 ### 5.1 能力类型与使用边界对比 把两个方案放到同一张表里对比能避免选错方向 | 对比维度 | MCP | Skill | | --- | --- | --- | | 核心作用 | 连接外部工具和数据源 | 注入任务流程和先验知识 | | 交付形态 | 独立进程或远程服务 | 文件夹 SKILL.md 脚本/资料 | | 运行方式 | 客户端通过 stdio/HTTP 调用 | 客户端在触发时注入提示上下文 | | 适合场景 | 查数据库、调接口、操作浏览器、读写文件 | 代码审查、文案改写、数据标注、固定业务 SOP | | 开发语言 | Python、TypeScript 等 | Markdown 为主脚本可选 | | 维护复杂度 | 需要处理进程、版本、依赖、日志 | 主要维护提示词质量和脚本逻辑 | | 出错影响 | 工具不可用或调用失败 | 模型不按流程执行输出质量不稳定 | 选择时先问一个问题这次扩展是给 Agent 增加“手”还是增加“大脑里的操作手册”。需要真实操作外部系统走 MCP需要约束判断标准和流程顺序走 Skill。 ### 5.2 开发成本和维护方式对比 MCP 的初期成本更高。你需要规划协议版本、传输方式、参数校验、错误处理和超时策略。一旦工具数量增多还要考虑权限边界避免一个 Agent 暴露过多危险操作。 Skill 的初期成本更低。写一份结构清晰的 SKILL.md 很快维护的重点是持续优化 description 和流程描述。但 Skill 的效果受提示词质量影响很大同一个 Skill 换一个模型版本表现可能明显不同。因此 Skill 也需要版本管理不能写完之后就不管。 ### 5.3 典型组合SOP 交给 Skill执行交给 MCP 实际项目最常见的是三件套组合MCP Server 暴露查询和操作能力Skill 定义业务 SOPAgent 负责判断和编排。 以一个内部运维助手为例 - MCP 提供服务状态查询、日志读取、进程重启三个工具。 - Skill 定义故障排查流程先看服务状态再查近 30 分钟错误日志定位异常模块最后决定是否需要重启。 - 模型在对话中判断用户请求属于“故障排查”于是加载 Skill 流程流程中每一步调用 MCP 工具。 这种结构下业务变更通常只改 Skill不改工具代码基础设施变更只改 MCP Server不改流程描述。职责分离后维护成本会低很多。 ## 6. 常见问题与排查链路 ### 6.1 MCP Server 注册后不生效 现象执行 claude mcp list 能看到 Server但对话中模型说找不到工具或者客户端启动后直接提示 MCP server not found。 检查顺序 - 确认 command 指向的 Python 环境安装过 mcp 包。使用绝对路径的虚拟环境 Python而不是裸 python。 - 确认 args 中是绝对路径且文件存在。 - 在终端手动运行 python order_server.py看是否能启动成功。MCP Server 启动后不会输出内容如果立即报错终端会显示异常堆栈。 - 检查代码中是否有多余的 print()。stdout 一旦被污染stdio 传输就会失败。 - 确认配置文件是合法 JSON。Claude Desktop 的配置文件中如果多了一个逗号整个配置都不会被读取。 ### 6.2 工具调用超时或返回异常 现象模型已经识别出应该调用工具但等待很久后提示失败或者返回结果明显错误。 可能原因和排查方式 - Server 内部函数抛异常。在本地单独调用函数或把异常捕捉后写入 stderr 日志。 - 参数传递错误。确认 docstring 中参数名与实际函数参数名一致模型依赖 docstring 生成参数。 - 网络或权限问题。如果函数内部访问外部接口需要在 Server 进程内验证连通性而不是在对话里验证。 - 返回数据过大。如果工具返回超大文本会造成上下文膨胀建议截断或只返回关键字段。 ### 6.3 Skill 加载后模型不按流程执行 现象Skill 目录存在SKILL.md 格式正确但模型仍然自由发挥。 优先检查三点 - description 是否写清楚了触发条件。用户提问没有命中描述时模型不会加载 Skill。 - Skill 目录是否放在客户端扫描的默认位置。不同客户端对 Skill 目录的约定不同放错位置就无法被发现。 - 对话中是否明确指定。在关键场景里可以要求模型先判断“这段话是否符合某个 Skill”或者在提问中直接点名 Skill。 ### 6.4 可复用的排查顺序清单 遇到 Agent 能力扩展不生效时按下面顺序排查不要跳跃 1. 输入是否正确问题文本、参数格式、任务描述。 2. 文件和路径是否正确MCP Server 文件、SKILL.md、脚本引用。 3. 依赖版本是否匹配mcp SDK、Python、Node.js、客户端版本。 4. 配置是否被客户端读取注册列表、配置文件语法。 5. 进程是否真正启动手动运行 Server查看 stderr。 6. 日志关键字是否有 ImportError、ConnectionError、TimeoutError。 7. 客户端限制当前版本是否支持所需的 MCP 原语或 Skill 特性。 ## 7. 生产实践建议安全、版本与可维护性 ### 7.1 MCP Server 的安全边界 学习环境里可以快速注册任意工具生产环境必须收紧权限。核心原则是最小权限 - 不要暴露危险命令。文件删除、代码执行、支付操作等工具要单独审批。 - 工具内部必须做参数校验。模型传进来的参数来自自然语言可能是空值、超长值或恶意内容。 - 数据库连接串、API Key 不要硬编码在 Server 代码中应通过环境变量注入。 - 远程 MCP Server 必须使用 HTTPS并在接入层做鉴权不能裸奔在公网。 - 对每次工具调用保留审计日志字段至少包含调用时间、工具名、参数摘要、返回状态。 ### 7.2 Skill 的版本管理和评审 SKILL.md 本质上是运行在模型上下文里的代码同样需要评审和版本管理。建议把 Skill 纳入 Git 仓库每次修改 description 或流程都要记录原因。 评审 Skill 时重点看四条 - description 是否命中预期的用户请求。 - 流程步骤是否可执行是否依赖不存在的脚本或资料。 - 输出格式是否稳定模型能否按统一结构产出结果。 - 是否有副作用例如要求模型读取不该读取的文件。 ### 7.3 从学习环境到生产环境的差异 最后用一张表总结学习环境与生产环境的区别 | 关注点 | 学习环境 | 生产环境 | | --- | --- | --- | | 配置 | 写在客户端配置文件里 | 外置配置中心支持动态刷新 | | 运行 | 本地 stdio 进程 | 独立部署进程守护健康检查 | | 日志 | 终端输出 | 结构化日志集中采集告警通知 | | 权限 | 全量暴露 | 最小权限按角色隔离 | | 版本 | 最新版即可 | 锁定版本灰度升级一键回滚 | | 监控 | 无 | 工具调用成功率、耗时、失败原因 | 学习阶段跑通最小案例是第一步但如果要把 MCP 和 Skill 用于线上业务必须把这六项补上。否则一次工具调用失败缺少日志和监控排查成本会非常高。 AI Agent 能力扩展的本质是把模型从“只会生成文本”变成“能执行、能查证、能按流程办事”。MCP 提供了标准化的能力接入方式Skill 提供了可维护的流程注入方式两者组合才能支撑复杂的真实业务。下一步建议从一个小场景入手先写一个只有两个工具的 MCP Server再写一个覆盖完整流程的 SKILL.md在一个真实任务里验证两者的配合。跑通之后再逐步引入鉴权、日志、版本控制和监控这套能力就能从玩具走向可用。