最近 AI 智能体开发的热度越来越高但在实际落地时很多开发者容易卡在同一个问题上模型明明有不错的对话能力可一接入业务系统就变得很笨不知道该调哪些工具、按什么顺序执行、输出格式怎么统一。尤其是 Claude Skills、MCP、Tools 这几个概念频繁出现在技术社区里不少同学分不清它们到底有什么区别。本文不绕弯子直接从这三者的边界讲起再给出一套可以复制运行的 Claude Skills 开发流程带你从 0 搭建一个具备企业级分工思路的 AI 智能体。无论你是初学者还是有一定经验的开发者都能从中拿到一套可落地的思路。1. 为什么 AI 智能体开发绕不开 Skills 与 MCP1.1 智能体的本质把“会聊天”变成“能办事”我们在使用大模型时最常见的形式是对话。你问一句模型答一句哪怕回答再专业本质上仍是“生成文本”。但 AI 智能体不同它需要调用外部系统、查询数据库、发送通知、生成文档、操作软件最后返回一个业务结果。举个最简单的例子普通对话你问“本周工单数量是多少”模型只能凭训练数据或上下文猜测。智能体系统连接工单数据库查询本周记录统计数量再按固定模板生成报告。这里的差别就在于智能体会“动手”。而要让它动手就必须给模型提供工具并约定工具的使用方式。这就引出了我们今天要聊的 Tools、MCP 和 Skills。1.2 一个容易混淆的认知误區很多入门文章会把 Skills 和 MCP 混在一起讲甚至在配置时觉得“只要接上了 MCP模型就具备所有能力了”。但实际上这两者是不同层次的东西MCP 解决的是“模型如何安全地调用外部工具”的通信协议问题。Skills 解决的是“模型在特定场景下应该如何完成一件完整任务”的流程与规范问题。换句话说MCP 更像是打通了水管Skills 则是告诉模型“先打开哪个阀门、接多少水、倒进哪个杯子”。只有协议没有流程模型仍然不知道在复杂业务里该按什么顺序做事。2. 核心概念拆解Tools、MCP、Skills2.1 Tools最基础的函数调用Tools 就是一组可以被模型调用执行特定操作的函数。开发者把函数名、参数说明、返回值格式暴露给模型模型在回答时根据用户问题决定是否调用某个 Tool。在代码层面一个 Tool 通常包含名称唯一标识例如query_work_orders描述说明该工具的作用、适用场景模型会借助描述决定是否调用它输入参数JSON Schema 形式声明明确每个参数的类型、含义、是否必填执行逻辑真正的业务处理代码返回值格式化后的文本或结构化数据所以Tools 是最小单元也可以看成是“模型世界”和“真实世界”之间的桥梁。2.2 MCP标准化的工具接入协议MCPModel Context Protocol模型上下文协议是 Anthropic 提出的一种开放协议它把工具接入方式标准化了。在没有 MCP 之前每个大模型平台都有自己的工具调用格式开发者要针对不同的模型写适配层企业内部每接入一个系统就要重新写一套工具注册逻辑。MCP 出现后工具提供方只需要实现一个 MCP Server模型客户端通过标准协议去发现、调用这个 Server 暴露的工具即可。MCP 带来的核心价值是统一接入规范工具描述、参数声明、调用结果都有统一结构。一次开发多处使用同一个 MCP Server 可以被不同支持 MCP 的客户端复用。权限边界更清晰MCP 支持定义工具列表、权限范围和访问控制适合企业级系统对接。2.3 Skills场景化能力封装让模型“会做完整的事”Skills 是比 Tools 更高一层的封装。一个 Skill 通常是一个文件夹里面包含SKILL.md描述这个技能是什么、在什么场景下使用、执行步骤、注意事项、输出要求相关脚本或模板例如 Python 脚本、Prompt 模板、配置文件、参考示例等当模型遇到符合该 Skill 的场景时会先读取 SKILL.md理解任务规范再调用 MCP/Tools 去执行实际操作。Skills 的典型使用场景包括生成符合企业规范的周报/日报按固定步骤排查线上故障根据团队约定生成需求文档和技术方案把零散数据整理成统一格式的报表所以Skills 更像是一个“岗位说明书”它告诉模型遇到这类任务你要按什么标准、什么顺序、什么输出格式去完成。2.4 三者的分工对照表概念解决的问题粒度举例Tools提供一个可执行的具体能力单个操作查询数据库、发送邮件、读取文件MCP统一模型与工具之间的通信协议接入层通过标准协议连接工单系统、GitLab、数据库Skills针对特定场景定义完整任务流程业务场景生成周报、故障排查、代码评审、方案撰写可以这样理解Tools 是单个工具MCP 是工具接入标准Skills 把多个工具组合成一个完整工作流。2.5 为什么不能只依赖 MCP不少开发者以为只要启动几个 MCP Server模型就自动变得强大。但实际体验下来会发现模型经常会遇到几个问题不知道在什么时机调用哪个 MCP 工具调用工具后不知道如何解读结果输出格式不稳定不同员工使用效果差异大缺少对业务规范和口径的约束。这些问题单靠 MCP 本身解决不了。Skills 的作用就是把这些“业务经验”沉淀下来让模型像一个有经验的新员工一样按标准流程办事。3. 环境准备与版本说明3.1 运行环境说明本文中的示例基于常见开发环境具体版本需要根据你的项目实际情况调整。我在准备环境时使用了以下条件操作系统macOS / Linux / Windows命令略有差异开发语言Python 3.10Node.js 环境有则更好部分 MCP Server 使用 TypeScript 开发模型客户端支持 Claude Skills 和 MCP 的工具例如 Claude Code 或其他兼容客户端3.2 安装 Claude Code示意以 Claude Code 为例安装方式通常是 CLI 工具可以通过 npm 全局安装。具体的包名和命令不同版本可能有所不同建议查阅官方 README 确认。# 安装 Claude Code示意命令 npm install -g anthropic-ai/claude-code安装完成后在项目目录下启动claude如果之前没有配置过认证信息首次启动时会引导你完成登录和授权。3.3 项目目录规划一个典型的 Skills 工程目录可以这样组织ai-agent-project/ ├── .claude/ │ └── skills/ │ ├── weekly-report/ │ │ ├── SKILL.md │ │ └── templates/ │ │ └── report_template.md │ └── incident-handler/ │ ├── SKILL.md │ └── scripts/ │ └── parse_logs.py ├── mcp-servers/ │ ├── work-order-server/ │ │ ├── pyproject.toml │ │ └── server.py │ └── README.md └── docs/ └── design.md这种组织方式把 Skills 与 MCP Server 分开便于维护和团队协作。4. 第一个 Claude Skills从创建到使用4.1 SKILL.md 的核心结构SKILL.md 是 Skills 的灵魂文件。它使用 Markdown 编写告诉模型下面几类关键信息技能名称一句话说明这个技能是做什么的。适用场景什么时候应该调用这个技能。执行步骤模型应遵循的完整操作流程。注意事项边界、禁忌、常见错误。输出规范最终输出的格式、模板或质量标准。下面是一个生成周报的 Skill 示例--- name: weekly-report description: 根据本周工作记录生成结构化周报适用于每周五提交周报的场景 --- # 周报生成技能 ## 适用场景 用户要求生成周报、工作总结或者需要把本周工作内容整理成汇报文档时使用本技能。 ## 执行步骤 1. 询问用户本周完成的主要事项或接收用户直接粘贴的工作记录。 2. 将工作内容按以下维度分类 - 需求开发 - 问题排查 - 技术优化 - 团队协作 3. 为每个类别提取 1-3 条核心事项使用动词开头的短句描述。 4. 对每条事项标注预计投入时间占比。 5. 按模板输出周报。 ## 输出格式 markdown ## 本周工作概览 本周共完成 X 项核心事项累计投入约 X 小时。 ### 需求开发 - [事项概述] ### 问题排查 - [事项概述] ### 技术优化 - [事项概述] ## 下周计划 1. [计划事项] 2. [计划事项]注意事项不要编造用户没有提到的工作内容。描述要精简每条控制在 20 字以内。如果用户提供的数据足够多优先采用用户数据而不是套用模板空话。在 SKILL.md 中name 和 description 是模型判断是否启用该技能的关键字段。description 写得越具体模型越容易在合适的时候找到它。 ### 4.2 在 Claude Code 中引入 Skills 把上面这个 weekly-report 文件夹放到项目的 .claude/skills/ 目录下.claude/skills/weekly-report/ ├── SKILL.md └── templates/ └── report_template.md之后启动 Claude Code在对话中输入帮我把这周的工作内容整理成周报完成了订单列表接口的性能优化QPS 从 200 提升到 800排查了线上支付回调超时的故障定位为第三方接口慢编写了团队内部的日志规范文档模型读到用户请求后会识别到“周报”场景自动读取 weekly-report 这个 Skill并按 SKILL.md 中的步骤输出结构化周报。 ### 4.3 为什么说 Skills 相当于可复用的经验 Skills 最大的优势是团队可以把最佳实践沉淀下来。 以前我们靠写 Prompt 模板让每个员工复制粘贴现在只需要维护一个 Skills 目录团队所有人共享同一套流程和规范。后续要改输出格式只需修改 SKILL.md所有使用该技能的任务都会同步生效。 ## 5. 用一个 MCP Server 打通企业数据 Skills 负责流程MCP 负责数据与工具接入。下面我用一个最简示例演示如何构建一个连接工单系统的 MCP Server并让 Skills 调用它。 ### 5.1 最简 MCP Server 示例 这里以 Python 为例。MCP 官方提供了 Python SDK安装方式可以参考对应仓库的 README。下面是一个核心逻辑示例演示如何暴露一个查询工单的工具 python # 文件路径mcp-servers/work-order-server/server.py from typing import Any import json # 根据所使用 SDK 不同导入方式会有差异以下为示意 # from mcp.server import Server, NotificationOptions # from mcp.server.models import InitializationOptions # 模拟工单数据实际项目中应替换为数据库查询 MOCK_ORDERS [ {id: WO001, title: 支付回调超时, status: 处理中}, {id: WO002, title: 订单列表加载慢, status: 已解决}, {id: WO003, title: 用户无法上传头像, status: 待分配}, ] def query_work_orders(status: str ) - str: 根据状态查询工单列表status 为空时返回全部工单 if status: orders [o for o in MOCK_ORDERS if o[status] status] else: orders MOCK_ORDERS return json.dumps(orders, ensure_asciiFalse, indent2) # ---- 以下为工具注册逻辑不同 SDK 版本写法不同这里只是演示思路 ---- TOOLS [ { name: query_work_orders, description: 查询工单列表支持按状态过滤状态可选处理中、已解决、待分配, inputSchema: { type: object, properties: { status: { type: string, description: 工单状态, enum: [处理中, 已解决, 待分配, ] } } } } ] def call_tool(name: str, arguments: dict) - str: if name query_work_orders: status arguments.get(status, ) return query_work_orders(status) raise ValueError(f未知工具: {name})实际开发中你需要按照 MCP SDK 的规范将上面的call_tool注册进 Server。这段代码的核心目的是展示一个 MCP 工具应具备的要素名称、描述、参数声明和业务逻辑。5.2 将 MCP Server 接入 Claude Code启动 MCP Server 后需要在模型客户端中注册。不同的客户端配置方式不同Claude Code 通常可以通过配置文件或命令添加。在 Claude Code 中可以使用类似下面的命令# 示意命令以实际版本为准 claude mcp add work-order-server -- python mcp-servers/work-order-server/server.py添加成功后可以在客户端里确认 MCP 工具是否加载例如执行工具列表查看命令。5.3 在 Skills 中调用 MCP 工具现在回到 Skills 的编写。假设我们不止要生成普通周报还要自动统计本周工单数据可以在 SKILL.md 中增加“调用外部数据”的步骤## 执行步骤 1. 使用 query_work_orders 工具查询本周工单列表。 2. 如果查询结果为空告知用户本周没有新增工单。 3. 对工单按状态分类统计数量。 4. 将统计数据写入周报的“问题排查”板块。这样一来Skill 负责定义“周报要怎么写、包含哪些板块”MCP 负责提供“工单数据从哪来”。这两者结合起来智能体才算真正具备了处理业务任务的能力。6. 从 0 搭建一个企业级 AI 智能体6.1 场景定义工单处理助手为了让整个流程更容易理解我们设计一个企业级场景企业内部需要一个 AI 助手帮助运维和客服人员处理工单。员工在对话中描述问题智能体自动查询工单系统、汇总相似问题、生成处理建议并按规范输出处理报告。这个场景覆盖了 Skills、MCP 和工具的完整组合适合作为学习案例。6.2 按职责拆分能力在动手写代码之前先把智能体的职责拆清楚能力层实现方式具体内容识别意图模型对话能力判断用户是要查工单、统计报表还是写处理建议查询数据MCP Server查询工单系统、读取员工信息、获取处理记录执行流程Skills按标准步骤完成工单分类、汇总、报告生成输出结果Skills 模板固定格式的处理报告这种分层的好处是职责单一、易于测试、后续要替换某一个系统时不会影响整体。6.3 编写处理报告 Skill下面是一个简化版的 SKILL.md 示例--- name: incident-handler description: 处理工单并生成处理报告适用于用户描述线上故障、用户投诉、系统异常等场景 --- # 工单处理技能 ## 适用场景 用户描述某个故障或异常需要查询工单、归类原因、输出处理报告时使用。 ## 执行步骤 1. 提取用户描述中的关键字系统名称、故障现象、影响范围。 2. 调用工单系统 MCP 工具查询最近 7 天相似工单。 3. 汇总相似工单的处理方案和处理结果。 4. 如果无法提取足够信息向用户确认以下内容 - 故障发生时间 - 影响用户范围 - 错误日志或截图 5. 按输出模板生成处理报告。 ## 输出格式 markdown ## 工单处理报告 ### 故障描述 [从用户输入中提取] ### 相似工单分析 | 工单ID | 标题 | 状态 | 解决方案 | | --- | --- | --- | --- | ### 处理建议 1. [基于相似工单归纳的处理方案] ### 待确认事项 - [如果信息不足列出需要补充的内容]注意事项不要虚构工单数据必须以 MCP 查询结果为准。相似工单需要按关键字段匹配例如系统名称、错误码、模块名称。如果查询结果为空明确告知用户而不是猜测处理方案。### 6.4 运行过程演示 当员工在智能体中输入以下内容时用户反馈今天上午 10 点左右用户在下单支付时遇到回调超时提示“请求超时”已经影响大约 20 笔订单。智能体的处理流程大致为 1. 提取关键词支付、回调超时、订单、请求超时。 2. 调用 query_work_orders查找“支付回调”相关的历史工单。 3. 查询到相似工单 WO001状态为“处理中”方案包含“检查第三方支付回调接口响应时间”。 4. 结合查询结果生成处理报告并提示用户补充错误码信息。 整个过程中模型先读取 Skill 得到流程再调用 MCP 工具获取数据最后按模板输出逻辑清晰、可追踪。 ### 6.5 企业部署时的安全设计 企业级智能体不能只考虑功能还要考虑安全边界。这里提供几个设计原则 - 最小权限MCP Server 暴露的工具只能访问智能体完成任务所必需的数据不要开放全库只读权限。 - 读操作与写操作分离查询类工具和更新类工具分开部署更新类工具需要额外的授权校验。 - 敏感信息脱敏MCP Server 返回的数据中涉及用户姓名、手机号、身份证等信息要提前脱敏。 - 操作审计每一次工具调用都应记录日志包括调用时间、用户身份、参数、返回结果。 ## 7. 常见问题与排查思路 在实际开发中以下几个问题出现频率最高。 ### 7.1 模型没有使用预期的 Skill | 问题现象 | 常见原因 | 解决思路 | | --- | --- | --- | | 对话中模型没有触发某个 Skill | SKILL.md 里的 description 描述不够明确 | 在 description 中补充触发词和适用场景 | | 多个 Skill 之间互相干扰 | 不同 Skill 的场景描述重叠 | 保证每个 Skill 的 name 和 description 具有清晰的边界 | | Skill 加载失败 | 目录结构不对或文件名错误 | 检查是否放在正确的 skills 目录下SKILL.md 大小写是否正确 | 建议给每个 Skill 写一个“不要使用本技能”的场景说明减少误触发。 ### 7.2 MCP Server 连接失败 | 问题现象 | 常见原因 | 解决思路 | | --- | --- | --- | | 工具列表为空 | MCP Server 启动失败 | 在终端单独运行 server 脚本确认没有报错 | | 调用工具超时 | 网络不通或服务地址配置错误 | 检查 MCP 配置中的 URL/命令参数 | | 返回数据格式错误 | JSON 序列化问题 | 确认返回值为字符串或符合协议要求的结构 | 排查顺序建议先启动 Server 看进程是否存活再在客户端里执行工具列表命令最后单独调用一个最简单的工具验证通路。 ### 7.3 Skill 与 MCP 的配合不生效 这个问题的常见原因是Skill 中虽然写了“调用工具”但模型不知道这个工具到底存在或者不知道调用条件。 解决办法很直接在 SKILL.md 中明确写出工具名称、入参和调用时机。例如 markdown 3. 调用 query_work_orders(status处理中) 获取处理中工单数量。有了明确的调用指引模型执行成功率会明显提升。8. 最佳实践与工程建议8.1 Skill 命名与目录规划Skills 目录使用kebab-case或snake_case例如weekly-report不要使用中文名。每个 Skill 必须有一个SKILL.md文件且name字段与目录名保持一致。复杂 Skill 的脚本、模板、示例数据分目录存放不要让 SKILL.md 无限膨胀。8.2 Skill 的粒度控制Skill 的粒度需要平衡。过粗的 Skill 缺乏具体指导过细的 Skill 难以复用。一个判断标准是如果一个 Skill 的描述超过 200 字且包含多个独立的业务流程建议拆分。例如“工单处理”可以拆成“工单查询”“工单分析”“报告生成”三个 Skill也可以保留为一个流程型 Skill关键是看团队实际使用频率。8.3 MCP Server 的稳定性生产环境建议使用进程守护工具管理 MCP Server 生命周期。对 MCP 的调用增加超时控制避免模型长时间等待。数据库类 MCP Server 必须使用只读账号并在网关层做额外限制。每次更新 MCP 工具后用自动化脚本验证工具描述和参数是否符合预期。8.4 日志与审计在企业内部使用智能体日志记录是刚需。建议至少记录以下信息用户请求内容触发了哪些 Skill调用了哪些 MCP 工具传入参数和返回结果摘要是否发生错误或降级日志不仅用于排查问题也可以用来持续优化 SKILL.md 的触发准确率。8.5 不要过度依赖模型自主编排虽然模型本身具备一定的任务编排能力但在企业场景中建议把关键步骤固化在 Skill 里而不是完全交给模型自由发挥。模型自由发挥适合原型验证固化流程才适合稳定上线。9. 总结与学习路线到这一步你已经掌握了几项关键能力能说清楚 Tools、MCP、Skills 三者的区别与分工会创建并配置一个最基础的 Claude Skills会编写一个简单的 MCP Server并接入到模型客户端能根据企业场景设计一个分层合理的 AI 智能体知道生产环境下的安全边界与最佳实践。接下来如果你想继续深入建议按下面的路线学习阅读官方文档中关于 Skills 与 MCP 的详细说明确认版本差异和最新用法。动手复现本文的两个示例周报生成 Skill 和工单查询 MCP Server。学习 MCP SDK 的源码结构理解工具注册、参数校验和会话管理机制。尝试把自己日常重复性工作改造成一个 Skill并逐步加入 MCP 工具调用。在企业项目中使用最小权限原则先做只读类工具验证稳定后再接入写操作。模型能力只是智能体的一部分真正决定智能体是否好用的往往是流程设计、工具规范和组织经验沉淀。SkILLs 这套机制正好把“经验”变成了可以复用、可以迭代、可以被团队共享的资产。建议你从一个小场景开始实践亲手写一个 Skill、接一个 MCP Server跑通之后再考虑更复杂的业务编排。 
长河君 · 2026/9/7 2:27:33 · 阅读 1.2k AI智能体开发实战：分清Tools、MCP与Claude Skills，从0搭建企业级应用
最近 AI 智能体开发的热度越来越高但在实际落地时很多开发者容易卡在同一个问题上模型明明有不错的对话能力可一接入业务系统就变得很笨不知道该调哪些工具、按什么顺序执行、输出格式怎么统一。尤其是 Claude Skills、MCP、Tools 这几个概念频繁出现在技术社区里不少同学分不清它们到底有什么区别。本文不绕弯子直接从这三者的边界讲起再给出一套可以复制运行的 Claude Skills 开发流程带你从 0 搭建一个具备企业级分工思路的 AI 智能体。无论你是初学者还是有一定经验的开发者都能从中拿到一套可落地的思路。1. 为什么 AI 智能体开发绕不开 Skills 与 MCP1.1 智能体的本质把“会聊天”变成“能办事”我们在使用大模型时最常见的形式是对话。你问一句模型答一句哪怕回答再专业本质上仍是“生成文本”。但 AI 智能体不同它需要调用外部系统、查询数据库、发送通知、生成文档、操作软件最后返回一个业务结果。举个最简单的例子普通对话你问“本周工单数量是多少”模型只能凭训练数据或上下文猜测。智能体系统连接工单数据库查询本周记录统计数量再按固定模板生成报告。这里的差别就在于智能体会“动手”。而要让它动手就必须给模型提供工具并约定工具的使用方式。这就引出了我们今天要聊的 Tools、MCP 和 Skills。1.2 一个容易混淆的认知误區很多入门文章会把 Skills 和 MCP 混在一起讲甚至在配置时觉得“只要接上了 MCP模型就具备所有能力了”。但实际上这两者是不同层次的东西MCP 解决的是“模型如何安全地调用外部工具”的通信协议问题。Skills 解决的是“模型在特定场景下应该如何完成一件完整任务”的流程与规范问题。换句话说MCP 更像是打通了水管Skills 则是告诉模型“先打开哪个阀门、接多少水、倒进哪个杯子”。只有协议没有流程模型仍然不知道在复杂业务里该按什么顺序做事。2. 核心概念拆解Tools、MCP、Skills2.1 Tools最基础的函数调用Tools 就是一组可以被模型调用执行特定操作的函数。开发者把函数名、参数说明、返回值格式暴露给模型模型在回答时根据用户问题决定是否调用某个 Tool。在代码层面一个 Tool 通常包含名称唯一标识例如query_work_orders描述说明该工具的作用、适用场景模型会借助描述决定是否调用它输入参数JSON Schema 形式声明明确每个参数的类型、含义、是否必填执行逻辑真正的业务处理代码返回值格式化后的文本或结构化数据所以Tools 是最小单元也可以看成是“模型世界”和“真实世界”之间的桥梁。2.2 MCP标准化的工具接入协议MCPModel Context Protocol模型上下文协议是 Anthropic 提出的一种开放协议它把工具接入方式标准化了。在没有 MCP 之前每个大模型平台都有自己的工具调用格式开发者要针对不同的模型写适配层企业内部每接入一个系统就要重新写一套工具注册逻辑。MCP 出现后工具提供方只需要实现一个 MCP Server模型客户端通过标准协议去发现、调用这个 Server 暴露的工具即可。MCP 带来的核心价值是统一接入规范工具描述、参数声明、调用结果都有统一结构。一次开发多处使用同一个 MCP Server 可以被不同支持 MCP 的客户端复用。权限边界更清晰MCP 支持定义工具列表、权限范围和访问控制适合企业级系统对接。2.3 Skills场景化能力封装让模型“会做完整的事”Skills 是比 Tools 更高一层的封装。一个 Skill 通常是一个文件夹里面包含SKILL.md描述这个技能是什么、在什么场景下使用、执行步骤、注意事项、输出要求相关脚本或模板例如 Python 脚本、Prompt 模板、配置文件、参考示例等当模型遇到符合该 Skill 的场景时会先读取 SKILL.md理解任务规范再调用 MCP/Tools 去执行实际操作。Skills 的典型使用场景包括生成符合企业规范的周报/日报按固定步骤排查线上故障根据团队约定生成需求文档和技术方案把零散数据整理成统一格式的报表所以Skills 更像是一个“岗位说明书”它告诉模型遇到这类任务你要按什么标准、什么顺序、什么输出格式去完成。2.4 三者的分工对照表概念解决的问题粒度举例Tools提供一个可执行的具体能力单个操作查询数据库、发送邮件、读取文件MCP统一模型与工具之间的通信协议接入层通过标准协议连接工单系统、GitLab、数据库Skills针对特定场景定义完整任务流程业务场景生成周报、故障排查、代码评审、方案撰写可以这样理解Tools 是单个工具MCP 是工具接入标准Skills 把多个工具组合成一个完整工作流。2.5 为什么不能只依赖 MCP不少开发者以为只要启动几个 MCP Server模型就自动变得强大。但实际体验下来会发现模型经常会遇到几个问题不知道在什么时机调用哪个 MCP 工具调用工具后不知道如何解读结果输出格式不稳定不同员工使用效果差异大缺少对业务规范和口径的约束。这些问题单靠 MCP 本身解决不了。Skills 的作用就是把这些“业务经验”沉淀下来让模型像一个有经验的新员工一样按标准流程办事。3. 环境准备与版本说明3.1 运行环境说明本文中的示例基于常见开发环境具体版本需要根据你的项目实际情况调整。我在准备环境时使用了以下条件操作系统macOS / Linux / Windows命令略有差异开发语言Python 3.10Node.js 环境有则更好部分 MCP Server 使用 TypeScript 开发模型客户端支持 Claude Skills 和 MCP 的工具例如 Claude Code 或其他兼容客户端3.2 安装 Claude Code示意以 Claude Code 为例安装方式通常是 CLI 工具可以通过 npm 全局安装。具体的包名和命令不同版本可能有所不同建议查阅官方 README 确认。# 安装 Claude Code示意命令 npm install -g anthropic-ai/claude-code安装完成后在项目目录下启动claude如果之前没有配置过认证信息首次启动时会引导你完成登录和授权。3.3 项目目录规划一个典型的 Skills 工程目录可以这样组织ai-agent-project/ ├── .claude/ │ └── skills/ │ ├── weekly-report/ │ │ ├── SKILL.md │ │ └── templates/ │ │ └── report_template.md │ └── incident-handler/ │ ├── SKILL.md │ └── scripts/ │ └── parse_logs.py ├── mcp-servers/ │ ├── work-order-server/ │ │ ├── pyproject.toml │ │ └── server.py │ └── README.md └── docs/ └── design.md这种组织方式把 Skills 与 MCP Server 分开便于维护和团队协作。4. 第一个 Claude Skills从创建到使用4.1 SKILL.md 的核心结构SKILL.md 是 Skills 的灵魂文件。它使用 Markdown 编写告诉模型下面几类关键信息技能名称一句话说明这个技能是做什么的。适用场景什么时候应该调用这个技能。执行步骤模型应遵循的完整操作流程。注意事项边界、禁忌、常见错误。输出规范最终输出的格式、模板或质量标准。下面是一个生成周报的 Skill 示例--- name: weekly-report description: 根据本周工作记录生成结构化周报适用于每周五提交周报的场景 --- # 周报生成技能 ## 适用场景 用户要求生成周报、工作总结或者需要把本周工作内容整理成汇报文档时使用本技能。 ## 执行步骤 1. 询问用户本周完成的主要事项或接收用户直接粘贴的工作记录。 2. 将工作内容按以下维度分类 - 需求开发 - 问题排查 - 技术优化 - 团队协作 3. 为每个类别提取 1-3 条核心事项使用动词开头的短句描述。 4. 对每条事项标注预计投入时间占比。 5. 按模板输出周报。 ## 输出格式 markdown ## 本周工作概览 本周共完成 X 项核心事项累计投入约 X 小时。 ### 需求开发 - [事项概述] ### 问题排查 - [事项概述] ### 技术优化 - [事项概述] ## 下周计划 1. [计划事项] 2. [计划事项]注意事项不要编造用户没有提到的工作内容。描述要精简每条控制在 20 字以内。如果用户提供的数据足够多优先采用用户数据而不是套用模板空话。在 SKILL.md 中name 和 description 是模型判断是否启用该技能的关键字段。description 写得越具体模型越容易在合适的时候找到它。 ### 4.2 在 Claude Code 中引入 Skills 把上面这个 weekly-report 文件夹放到项目的 .claude/skills/ 目录下.claude/skills/weekly-report/ ├── SKILL.md └── templates/ └── report_template.md之后启动 Claude Code在对话中输入帮我把这周的工作内容整理成周报完成了订单列表接口的性能优化QPS 从 200 提升到 800排查了线上支付回调超时的故障定位为第三方接口慢编写了团队内部的日志规范文档模型读到用户请求后会识别到“周报”场景自动读取 weekly-report 这个 Skill并按 SKILL.md 中的步骤输出结构化周报。 ### 4.3 为什么说 Skills 相当于可复用的经验 Skills 最大的优势是团队可以把最佳实践沉淀下来。 以前我们靠写 Prompt 模板让每个员工复制粘贴现在只需要维护一个 Skills 目录团队所有人共享同一套流程和规范。后续要改输出格式只需修改 SKILL.md所有使用该技能的任务都会同步生效。 ## 5. 用一个 MCP Server 打通企业数据 Skills 负责流程MCP 负责数据与工具接入。下面我用一个最简示例演示如何构建一个连接工单系统的 MCP Server并让 Skills 调用它。 ### 5.1 最简 MCP Server 示例 这里以 Python 为例。MCP 官方提供了 Python SDK安装方式可以参考对应仓库的 README。下面是一个核心逻辑示例演示如何暴露一个查询工单的工具 python # 文件路径mcp-servers/work-order-server/server.py from typing import Any import json # 根据所使用 SDK 不同导入方式会有差异以下为示意 # from mcp.server import Server, NotificationOptions # from mcp.server.models import InitializationOptions # 模拟工单数据实际项目中应替换为数据库查询 MOCK_ORDERS [ {id: WO001, title: 支付回调超时, status: 处理中}, {id: WO002, title: 订单列表加载慢, status: 已解决}, {id: WO003, title: 用户无法上传头像, status: 待分配}, ] def query_work_orders(status: str ) - str: 根据状态查询工单列表status 为空时返回全部工单 if status: orders [o for o in MOCK_ORDERS if o[status] status] else: orders MOCK_ORDERS return json.dumps(orders, ensure_asciiFalse, indent2) # ---- 以下为工具注册逻辑不同 SDK 版本写法不同这里只是演示思路 ---- TOOLS [ { name: query_work_orders, description: 查询工单列表支持按状态过滤状态可选处理中、已解决、待分配, inputSchema: { type: object, properties: { status: { type: string, description: 工单状态, enum: [处理中, 已解决, 待分配, ] } } } } ] def call_tool(name: str, arguments: dict) - str: if name query_work_orders: status arguments.get(status, ) return query_work_orders(status) raise ValueError(f未知工具: {name})实际开发中你需要按照 MCP SDK 的规范将上面的call_tool注册进 Server。这段代码的核心目的是展示一个 MCP 工具应具备的要素名称、描述、参数声明和业务逻辑。5.2 将 MCP Server 接入 Claude Code启动 MCP Server 后需要在模型客户端中注册。不同的客户端配置方式不同Claude Code 通常可以通过配置文件或命令添加。在 Claude Code 中可以使用类似下面的命令# 示意命令以实际版本为准 claude mcp add work-order-server -- python mcp-servers/work-order-server/server.py添加成功后可以在客户端里确认 MCP 工具是否加载例如执行工具列表查看命令。5.3 在 Skills 中调用 MCP 工具现在回到 Skills 的编写。假设我们不止要生成普通周报还要自动统计本周工单数据可以在 SKILL.md 中增加“调用外部数据”的步骤## 执行步骤 1. 使用 query_work_orders 工具查询本周工单列表。 2. 如果查询结果为空告知用户本周没有新增工单。 3. 对工单按状态分类统计数量。 4. 将统计数据写入周报的“问题排查”板块。这样一来Skill 负责定义“周报要怎么写、包含哪些板块”MCP 负责提供“工单数据从哪来”。这两者结合起来智能体才算真正具备了处理业务任务的能力。6. 从 0 搭建一个企业级 AI 智能体6.1 场景定义工单处理助手为了让整个流程更容易理解我们设计一个企业级场景企业内部需要一个 AI 助手帮助运维和客服人员处理工单。员工在对话中描述问题智能体自动查询工单系统、汇总相似问题、生成处理建议并按规范输出处理报告。这个场景覆盖了 Skills、MCP 和工具的完整组合适合作为学习案例。6.2 按职责拆分能力在动手写代码之前先把智能体的职责拆清楚能力层实现方式具体内容识别意图模型对话能力判断用户是要查工单、统计报表还是写处理建议查询数据MCP Server查询工单系统、读取员工信息、获取处理记录执行流程Skills按标准步骤完成工单分类、汇总、报告生成输出结果Skills 模板固定格式的处理报告这种分层的好处是职责单一、易于测试、后续要替换某一个系统时不会影响整体。6.3 编写处理报告 Skill下面是一个简化版的 SKILL.md 示例--- name: incident-handler description: 处理工单并生成处理报告适用于用户描述线上故障、用户投诉、系统异常等场景 --- # 工单处理技能 ## 适用场景 用户描述某个故障或异常需要查询工单、归类原因、输出处理报告时使用。 ## 执行步骤 1. 提取用户描述中的关键字系统名称、故障现象、影响范围。 2. 调用工单系统 MCP 工具查询最近 7 天相似工单。 3. 汇总相似工单的处理方案和处理结果。 4. 如果无法提取足够信息向用户确认以下内容 - 故障发生时间 - 影响用户范围 - 错误日志或截图 5. 按输出模板生成处理报告。 ## 输出格式 markdown ## 工单处理报告 ### 故障描述 [从用户输入中提取] ### 相似工单分析 | 工单ID | 标题 | 状态 | 解决方案 | | --- | --- | --- | --- | ### 处理建议 1. [基于相似工单归纳的处理方案] ### 待确认事项 - [如果信息不足列出需要补充的内容]注意事项不要虚构工单数据必须以 MCP 查询结果为准。相似工单需要按关键字段匹配例如系统名称、错误码、模块名称。如果查询结果为空明确告知用户而不是猜测处理方案。### 6.4 运行过程演示 当员工在智能体中输入以下内容时用户反馈今天上午 10 点左右用户在下单支付时遇到回调超时提示“请求超时”已经影响大约 20 笔订单。智能体的处理流程大致为 1. 提取关键词支付、回调超时、订单、请求超时。 2. 调用 query_work_orders查找“支付回调”相关的历史工单。 3. 查询到相似工单 WO001状态为“处理中”方案包含“检查第三方支付回调接口响应时间”。 4. 结合查询结果生成处理报告并提示用户补充错误码信息。 整个过程中模型先读取 Skill 得到流程再调用 MCP 工具获取数据最后按模板输出逻辑清晰、可追踪。 ### 6.5 企业部署时的安全设计 企业级智能体不能只考虑功能还要考虑安全边界。这里提供几个设计原则 - 最小权限MCP Server 暴露的工具只能访问智能体完成任务所必需的数据不要开放全库只读权限。 - 读操作与写操作分离查询类工具和更新类工具分开部署更新类工具需要额外的授权校验。 - 敏感信息脱敏MCP Server 返回的数据中涉及用户姓名、手机号、身份证等信息要提前脱敏。 - 操作审计每一次工具调用都应记录日志包括调用时间、用户身份、参数、返回结果。 ## 7. 常见问题与排查思路 在实际开发中以下几个问题出现频率最高。 ### 7.1 模型没有使用预期的 Skill | 问题现象 | 常见原因 | 解决思路 | | --- | --- | --- | | 对话中模型没有触发某个 Skill | SKILL.md 里的 description 描述不够明确 | 在 description 中补充触发词和适用场景 | | 多个 Skill 之间互相干扰 | 不同 Skill 的场景描述重叠 | 保证每个 Skill 的 name 和 description 具有清晰的边界 | | Skill 加载失败 | 目录结构不对或文件名错误 | 检查是否放在正确的 skills 目录下SKILL.md 大小写是否正确 | 建议给每个 Skill 写一个“不要使用本技能”的场景说明减少误触发。 ### 7.2 MCP Server 连接失败 | 问题现象 | 常见原因 | 解决思路 | | --- | --- | --- | | 工具列表为空 | MCP Server 启动失败 | 在终端单独运行 server 脚本确认没有报错 | | 调用工具超时 | 网络不通或服务地址配置错误 | 检查 MCP 配置中的 URL/命令参数 | | 返回数据格式错误 | JSON 序列化问题 | 确认返回值为字符串或符合协议要求的结构 | 排查顺序建议先启动 Server 看进程是否存活再在客户端里执行工具列表命令最后单独调用一个最简单的工具验证通路。 ### 7.3 Skill 与 MCP 的配合不生效 这个问题的常见原因是Skill 中虽然写了“调用工具”但模型不知道这个工具到底存在或者不知道调用条件。 解决办法很直接在 SKILL.md 中明确写出工具名称、入参和调用时机。例如 markdown 3. 调用 query_work_orders(status处理中) 获取处理中工单数量。有了明确的调用指引模型执行成功率会明显提升。8. 最佳实践与工程建议8.1 Skill 命名与目录规划Skills 目录使用kebab-case或snake_case例如weekly-report不要使用中文名。每个 Skill 必须有一个SKILL.md文件且name字段与目录名保持一致。复杂 Skill 的脚本、模板、示例数据分目录存放不要让 SKILL.md 无限膨胀。8.2 Skill 的粒度控制Skill 的粒度需要平衡。过粗的 Skill 缺乏具体指导过细的 Skill 难以复用。一个判断标准是如果一个 Skill 的描述超过 200 字且包含多个独立的业务流程建议拆分。例如“工单处理”可以拆成“工单查询”“工单分析”“报告生成”三个 Skill也可以保留为一个流程型 Skill关键是看团队实际使用频率。8.3 MCP Server 的稳定性生产环境建议使用进程守护工具管理 MCP Server 生命周期。对 MCP 的调用增加超时控制避免模型长时间等待。数据库类 MCP Server 必须使用只读账号并在网关层做额外限制。每次更新 MCP 工具后用自动化脚本验证工具描述和参数是否符合预期。8.4 日志与审计在企业内部使用智能体日志记录是刚需。建议至少记录以下信息用户请求内容触发了哪些 Skill调用了哪些 MCP 工具传入参数和返回结果摘要是否发生错误或降级日志不仅用于排查问题也可以用来持续优化 SKILL.md 的触发准确率。8.5 不要过度依赖模型自主编排虽然模型本身具备一定的任务编排能力但在企业场景中建议把关键步骤固化在 Skill 里而不是完全交给模型自由发挥。模型自由发挥适合原型验证固化流程才适合稳定上线。9. 总结与学习路线到这一步你已经掌握了几项关键能力能说清楚 Tools、MCP、Skills 三者的区别与分工会创建并配置一个最基础的 Claude Skills会编写一个简单的 MCP Server并接入到模型客户端能根据企业场景设计一个分层合理的 AI 智能体知道生产环境下的安全边界与最佳实践。接下来如果你想继续深入建议按下面的路线学习阅读官方文档中关于 Skills 与 MCP 的详细说明确认版本差异和最新用法。动手复现本文的两个示例周报生成 Skill 和工单查询 MCP Server。学习 MCP SDK 的源码结构理解工具注册、参数校验和会话管理机制。尝试把自己日常重复性工作改造成一个 Skill并逐步加入 MCP 工具调用。在企业项目中使用最小权限原则先做只读类工具验证稳定后再接入写操作。模型能力只是智能体的一部分真正决定智能体是否好用的往往是流程设计、工具规范和组织经验沉淀。SkILLs 这套机制正好把“经验”变成了可以复用、可以迭代、可以被团队共享的资产。建议你从一个小场景开始实践亲手写一个 Skill、接一个 MCP Server跑通之后再考虑更复杂的业务编排。