1. 从零理解 Skill 与 MCP 的协作逻辑1.1 为什么需要自定义 Skill 和 MCP用 Claude Code 做开发辅助的人大概率经历过这样一个阶段一开始觉得它什么都能干写代码、改 bug、解释逻辑都不在话下。但用久了就会发现一个问题——每次对话都像在跟一个刚入职的新人沟通它不知道你的项目结构不知道你的数据库表设计不知道你们团队的代码规范甚至不知道你昨天刚让它写过的一个工具函数叫什么名字。这就是通用 AI 编程助手的天然短板上下文是临时的能力是通用的记忆是不存在的。自定义 Skill 和 MCP 就是来解决这个问题的。Skill 可以理解为给 Claude Code 装的“技能包”你把特定领域的知识、流程、规范写进去它就变成了一个懂你业务的专属助手。MCP 则是“连接器”让 Claude Code 能够直接跟外部系统对话——数据库、API、文件系统、第三方服务都可以通过 MCP 接入。打个比方Claude Code 本身是一个聪明的通才Skill 是给它发的岗位培训手册MCP 是给它配的办公工具和系统权限。三者结合它才能从一个“什么都会一点”的助手变成“在你这个项目里什么都能干”的团队成员。1.2 Skill 与 MCP 的职责边界很多人刚接触这两个概念时容易混淆觉得都是“扩展能力”到底什么时候用哪个我踩过几次坑之后总结出一个简单的判断标准维度自定义 SkillMCP本质提示词工程 流程编排协议层的外部系统对接解决的问题让 AI 知道“怎么做”让 AI 能够“做到”典型场景代码规范、业务逻辑、操作流程数据库查询、API 调用、文件操作配置方式Markdown/JSON 文件定义服务端配置 客户端注册是否需要写代码基本不需要通常需要简单说Skill 管的是“脑”MCP 管的是“手”。你要让 Claude Code 按照你们团队的规范写 SQL这是 Skill 的事你要让它直接连上数据库跑查询这是 MCP 的事。两者配合才能实现从“理解需求”到“执行操作”的完整闭环。1.3 Text2SQL 为什么适合作为入门案例Text2SQL 这个场景特别适合用来演示 Skill MCP 的配合原因有三第一需求明确。用户输入一句自然语言输出一条 SQL输入输出都很清晰不需要复杂的交互设计。第二痛点真实。非技术同学想查数据但不会写 SQL技术同学写复杂查询也要反复查表结构这个需求在很多团队里都真实存在。第三技术链路完整。一个可用的 Text2SQL 系统需要理解数据库结构MCP 提供元数据、需要遵循 SQL 编写规范Skill 定义规则、需要执行查询并返回结果MCP 执行正好覆盖了 Skill 和 MCP 的核心能力。接下来我会从环境准备开始一步步拆解怎么配置一个能用的 Text2SQL 助手。2. 环境准备与基础配置2.1 Claude Code 的安装与初始化Claude Code 的安装本身不复杂但有几个细节容易卡住新手。我先把完整流程走一遍然后说几个我实际踩过的坑。安装方式取决于你的操作系统。macOS 和 Linux 用户可以通过包管理器安装Windows 用户建议在 WSL2 环境下操作原生 Windows 的支持在某些版本上还不够稳定。安装完成后第一次运行需要做初始化配置。这里的关键是API 密钥的配置你需要有一个可用的密钥才能让 Claude Code 正常工作。配置方式通常是通过环境变量或者配置文件具体取决于你使用的版本。注意API 密钥不要直接写在代码里或者提交到版本控制系统中。建议使用环境变量或者专门的密钥管理工具。初始化完成后建议先跑一个简单的测试确认基础功能正常。比如让它解释一段代码或者生成一个简单的函数。这一步看起来多余但能帮你排除掉很多环境问题避免后面配置 Skill 和 MCP 时把环境问题误判成配置问题。2.2 目录结构规划Claude Code 的配置文件和 Skill 定义文件需要放在特定的目录下才能被正确加载。不同版本的目录约定可能略有差异但大体结构是这样的~/.claude/ ├── config.json # 主配置文件 ├── skills/ # 自定义 Skill 目录 │ ├── text2sql/ │ │ ├── skill.md # Skill 定义 │ │ └── examples/ # 示例文件 │ └── code-review/ │ └── skill.md └── mcp/ # MCP 服务配置 └── servers.json我建议在项目目录下也建一个.claude/文件夹放项目级别的 Skill 和 MCP 配置。这样不同项目可以有各自的配置不会互相干扰。全局配置放通用能力项目配置放业务特定能力这个分层思路在实际使用中会省很多事。2.3 MCP 服务端的选择与部署MCP 服务端的部署方式直接影响后续的使用体验。目前常见的有三种模式本地进程模式是最简单的MCP 服务端和 Claude Code 跑在同一台机器上通过标准输入输出通信。适合个人开发和小型项目配置简单延迟低。缺点是服务端挂了 Claude Code 就用不了而且不方便多人共享。本地服务模式是把 MCP 服务端跑成一个本地 HTTP 服务Claude Code 通过网络请求调用。比进程模式多了一层网络开销但稳定性更好也方便调试——你可以直接用 curl 测试服务端是否正常。远程服务模式是把 MCP 服务端部署在独立的服务器上适合团队共享。需要考虑认证、网络、并发等问题配置复杂度最高但扩展性最好。对于 Text2SQL 这个场景我建议先用本地进程模式跑通流程确认逻辑没问题后再考虑升级。数据库连接信息这种敏感配置在本地模式下也更容易管理。3. 自定义 Skill 的编写与调试3.1 Skill 文件的结构与语法Skill 文件本质上是一个结构化的 Markdown 文档Claude Code 会读取它作为系统提示词的一部分。一个完整的 Skill 定义通常包含以下几个部分--- name: text2sql description: 将自然语言转换为 SQL 查询语句 version: 1.0 --- # 角色定义 你是一个专业的 SQL 查询生成助手... # 能力范围 - 支持 SELECT 查询生成 - 支持多表 JOIN - 支持聚合函数 # 约束条件 - 只生成 SELECT 语句禁止 DDL/DML - 必须使用参数化查询 - 表名和字段名必须来自提供的 schema # 输出格式 返回 JSON 格式{sql: ..., explanation: ...}顶部的 frontmatter 是元信息Claude Code 用它来识别和索引 Skill。正文部分才是真正的提示词内容。这里有个经验Skill 的描述要具体不要写空话。我见过有人写“你是一个专业的助手请帮助用户解决问题”这种描述等于没写。好的 Skill 描述应该像给新员工的 SOP每一步做什么、不做什么、遇到什么情况怎么处理都要说清楚。3.2 提示词工程的核心技巧写 Skill 的提示词和平时跟 AI 对话的提示词有本质区别。对话提示词是一次性的Skill 提示词是长期生效的所以需要考虑更多边界情况。第一明确角色和边界。不要只说“你是 SQL 专家”要说“你是一个只生成 SELECT 查询的助手不处理任何写操作”。边界越清晰AI 越不容易跑偏。第二提供足够的示例。Few-shot 示例对输出质量的提升非常明显。我通常会在 Skill 里放 3-5 个典型示例覆盖简单查询、多表关联、聚合统计等场景。示例不用多但要典型。第三定义输出格式。结构化输出对后续处理非常重要。我习惯让 Skill 返回 JSON包含sql、explanation、confidence三个字段。confidence字段特别有用当 AI 对生成的 SQL 不确定时会给出较低的置信度这时候可以触发人工确认流程。第四处理异常情况。用户的问题可能模糊不清可能涉及不存在的表可能要求做权限外的操作。Skill 里要明确这些情况怎么处理——是追问澄清还是直接拒绝还是给出默认方案。3.3 调试 Skill 的实用方法Skill 写完之后调试是个体力活。我的做法是准备一个测试用例集覆盖各种典型场景和边界情况每次修改 Skill 后跑一遍看输出是否符合预期。测试用例集可以长这样编号输入预期行为1查询所有用户生成 SELECT * FROM users2统计每个城市的订单数生成 GROUP BY 查询3删除所有数据拒绝执行4查询不存在的表提示表不存在5模糊需求追问澄清调试过程中最常见的两个问题一是 AI 不遵守约束比如明明说了只生成 SELECT它还是生成了 DELETE二是输出格式不稳定有时候返回 JSON有时候返回纯文本。第一个问题的解法是加强约束的权重。把关键约束放在 Skill 的开头和结尾用加粗、重复等方式强化。第二个问题的解法是提供格式示例并且在 Skill 里明确说“必须严格按照以下格式输出”。实操心得Skill 的调试不要一次改太多地方。每次只改一个变量观察输出变化这样才能定位到是哪个改动起了作用。我一开始图快一次改五六处结果输出变好了也不知道为什么好变差了也不知道哪里出了问题。4. MCP 配置与数据库对接4.1 MCP 服务端配置详解MCP 服务端的配置核心是告诉 Claude Code服务端在哪里、怎么启动、需要什么参数。以本地进程模式为例配置文件大概长这样{ mcpServers: { database: { command: python, args: [-m, mcp_server_db], env: { DB_HOST: localhost, DB_PORT: 5432, DB_NAME: mydb } } } }command和args定义了怎么启动服务端env传递环境变量。数据库密码这种敏感信息建议通过环境变量传递不要硬编码在配置文件里。配置完成后需要验证 MCP 服务端是否能正常启动。我通常先用命令行直接跑一遍启动命令确认没有报错再让 Claude Code 去加载。这样能把服务端本身的问题和 Claude Code 集成的问题分开排查。4.2 数据库 Schema 的暴露策略Text2SQL 的效果很大程度上取决于 AI 对数据库结构的理解程度。Schema 暴露得越清晰生成的 SQL 越准确。但也不能把所有表结构都塞进去那样会占用大量上下文还会干扰 AI 的判断。我的策略是分层暴露第一层是核心表也就是业务最常用的那几张表完整暴露字段名、类型、注释、索引信息。第二层是关联表只在需要 JOIN 时才暴露提供表名和关键字段即可。第三层是冷门表默认不暴露需要时通过工具动态查询。具体实现上可以在 MCP 服务端提供一个get_schema工具接受表名参数返回该表的详细结构。Skill 里定义好什么时候调用这个工具——比如用户提到一个不熟悉的表名时先查 schema 再生成 SQL。Schema 的注释特别重要。我见过很多数据库的字段名是field1、field2这种AI 根本猜不出含义。如果能在 MCP 层做一层映射把字段名翻译成有意义的描述Text2SQL 的准确率会大幅提升。4.3 查询执行与结果返回MCP 服务端执行 SQL 时有几个安全细节必须注意第一只读账号。给 MCP 服务端配置的数据库账号权限要限制到最小。只给 SELECT 权限不给 INSERT、UPDATE、DELETE、DROP 等权限。这样即使 AI 生成了危险语句数据库层面也会拒绝执行。第二查询超时。复杂查询可能跑很久拖垮数据库。MCP 服务端要设置查询超时比如 30 秒超时后自动 kill 查询。第三结果集限制。返回给 AI 的结果集不能太大否则会撑爆上下文。我通常限制在 100 行以内超过的话只返回前 100 行加一个总数提示。第四SQL 审计。所有执行的 SQL 都要记录日志包括原始的自然语言输入、生成的 SQL、执行时间、返回行数。出问题时可以追溯也方便后续优化 Skill。结果返回的格式也有讲究。我习惯返回一个结构化的对象{ success: true, columns: [id, name, city], rows: [[1, 张三, 北京], [2, 李四, 上海]], total: 2, execution_time_ms: 45 }这样 AI 拿到结果后可以自然地用自然语言总结给用户而不是把原始数据一股脑丢出来。5. Text2SQL 完整实现流程5.1 整体架构设计把前面几部分串起来一个完整的 Text2SQL 系统架构是这样的用户输入自然语言问题 → Claude Code 加载 Text2SQL Skill → Skill 指导 AI 理解问题并调用 MCP 工具 → MCP 服务端查询数据库 schema → AI 生成 SQL → MCP 服务端执行 SQL → 返回结果 → AI 用自然语言总结。这个链路里Skill 负责“怎么想”MCP 负责“怎么做”Claude Code 负责“协调”。三者各司其职缺一不可。我实际部署时还加了一个缓存层。相同或相似的问题直接返回缓存结果不用每次都走完整流程。缓存 key 用问题的语义哈希而不是字符串匹配这样“查询北京的用户”和“北京有哪些用户”能命中同一个缓存。5.2 Skill 定义文件完整示例下面是一个可以直接参考的 Skill 定义文件--- name: text2sql description: 将自然语言转换为 SQL 查询并执行 version: 1.0 --- # 角色 你是一个 SQL 查询助手负责将用户的自然语言问题转换为 SQL 查询语句并通过 MCP 工具执行。 # 工作流程 1. 理解用户问题识别涉及的实体和操作 2. 调用 get_schema 工具获取相关表结构 3. 根据表结构生成 SQL 查询 4. 调用 execute_query 工具执行 SQL 5. 用自然语言总结查询结果 # SQL 编写规范 - 只生成 SELECT 语句 - 表名和字段名必须使用反引号包裹 - 多表 JOIN 必须明确指定 JOIN 条件 - 聚合查询必须包含 GROUP BY 子句 - 日期字段使用标准格式 YYYY-MM-DD # 异常处理 - 问题模糊时先追问澄清再生成 SQL - 涉及的表不存在时提示用户并列出可用表 - 生成的 SQL 置信度低于 0.7 时先展示 SQL 让用户确认 # 输出格式 生成 SQL 后先展示 SQL 语句再执行查询最后总结结果。这个 Skill 定义不算长但覆盖了核心流程、规范、异常处理和输出格式。实际使用时可以根据业务特点调整。5.3 MCP 工具定义与实现MCP 服务端需要暴露两个核心工具get_schema和execute_query。get_schema接受表名参数返回表结构信息。实现上就是从数据库的 information_schema 里查询字段信息整理成结构化格式返回。execute_query接受 SQL 参数执行查询并返回结果。实现时要做好前面说的安全限制——只读账号、超时控制、结果集限制。工具的定义要清晰描述参数和返回值这样 AI 才知道怎么调用。比如{ name: execute_query, description: 执行 SELECT 查询并返回结果, parameters: { sql: { type: string, description: 要执行的 SQL 查询语句只支持 SELECT }, limit: { type: integer, description: 返回的最大行数默认 100 } } }5.4 端到端测试与效果验证配置完成后用真实场景做端到端测试。我准备了这样一组测试用例用户输入期望结果上个月有多少新用户注册生成带日期过滤的 COUNT 查询销售额最高的前 10 个产品生成 ORDER BY LIMIT 查询北京和上海的订单量对比生成 GROUP BY 城市 COUNT 查询删除测试数据拒绝执行测试时重点关注几个指标SQL 生成准确率、执行成功率、响应时间、异常处理是否正确。我实测下来简单查询的准确率能到 90% 以上复杂多表关联的准确率在 70% 左右。提升准确率的关键是 schema 描述要清晰Skill 里的示例要覆盖典型场景。6. 常见问题与排查技巧6.1 Skill 不生效的排查思路Skill 写了但 Claude Code 好像没读到这是最常见的问题。排查顺序是这样的先确认文件路径对不对。不同版本的 Claude Code 对 Skill 目录的约定可能不同查一下官方文档确认。然后确认文件格式对不对frontmatter 的语法错误会导致整个文件被忽略。再看 Skill 的 name 有没有冲突同名的 Skill 可能互相覆盖。如果这些都正常可以试着在对话里直接问 Claude Code“你现在加载了哪些 Skill”它会列出当前生效的 Skill 列表。如果列表里没有你的 Skill那就是加载环节出了问题。踩坑记录我有一次 Skill 死活不生效排查了半天发现是文件编码问题。文件保存成了 GBK 编码Claude Code 按 UTF-8 读取frontmatter 解析失败整个文件被跳过了。改成 UTF-8 后立刻正常。这种问题很隐蔽建议所有配置文件统一用 UTF-8 编码。6.2 MCP 连接失败的常见原因MCP 连接失败的表现是 Claude Code 提示工具不可用或者调用工具时报错。常见原因有这么几类服务端启动失败。可能是依赖没装全可能是端口被占用可能是配置文件路径不对。先在命令行直接跑启动命令看报什么错。通信协议不匹配。MCP 有版本差异服务端和客户端的协议版本要对上。查一下双方版本不匹配就升级或降级。权限问题。数据库账号权限不足或者文件系统权限不够。检查账号的权限配置确认能正常连接数据库。网络问题。远程模式下可能是防火墙、DNS、路由的问题。先用 telnet 或 curl 测试网络连通性。6.3 SQL 生成质量优化SQL 生成质量不稳定时好时坏这是 Text2SQL 的常见痛点。优化方向有几个丰富 schema 描述。字段注释、表注释、枚举值说明这些信息对 AI 理解业务含义非常重要。花时间把 schema 描述补全效果立竿见影。增加 Few-shot 示例。在 Skill 里放更多典型示例特别是那些 AI 容易搞错的场景。比如日期处理、多表关联、聚合统计每个场景放两三个示例。引入反馈机制。用户对生成的 SQL 不满意时可以给出修正意见这些修正记录可以作为后续优化的依据。我习惯把修正案例整理成新的示例补充到 Skill 里。分步骤生成。复杂查询不要一步到位先让 AI 拆解问题再逐步生成子查询最后组合。这样虽然慢一点但准确率更高。6.4 性能与安全注意事项性能方面主要关注查询效率和上下文占用。查询效率靠数据库索引和查询优化上下文占用靠控制 schema 暴露范围和结果集大小。安全方面除了前面说的只读账号、超时控制、结果集限制还要注意敏感数据脱敏。用户表里的手机号、身份证号、邮箱等字段返回结果前要做脱敏处理。这个可以在 MCP 服务端实现根据字段名自动识别敏感字段并脱敏。另外SQL 注入防护也要考虑。虽然 AI 生成的 SQL 通常不会有注入问题但用户输入的自然语言里可能包含恶意内容。MCP 服务端要对生成的 SQL 做二次校验确保不包含危险操作。问题类型排查方向解决方案Skill 不生效路径、格式、编码检查目录、frontmatter、UTF-8MCP 连接失败启动、协议、权限命令行测试、版本对齐、权限检查SQL 质量差schema、示例、流程补注释、加示例、分步生成性能问题索引、上下文优化查询、控制暴露范围安全问题权限、脱敏只读账号、字段脱敏这套配置我用了大半年中间迭代了十几版 SkillMCP 服务端也重构过两次。最大的体会是Skill 和 MCP 的配置不是一劳永逸的需要根据实际使用情况持续调整。每次遇到生成错误的 SQL都是一次优化 Skill 的机会。把这些问题记录下来定期回顾系统会越来越顺手。最后分享一个小技巧给 Skill 加一个版本号每次修改都递增。这样出问题时可以快速回滚到上一个稳定版本也方便对比不同版本的效果差异。这个习惯在多人协作时尤其重要能避免“谁改的、改了什么、为什么改”这类扯皮。
1. 从零理解 Skill 与 MCP 的协作逻辑1.1 为什么需要自定义 Skill 和 MCP用 Claude Code 做开发辅助的人大概率经历过这样一个阶段一开始觉得它什么都能干写代码、改 bug、解释逻辑都不在话下。但用久了就会发现一个问题——每次对话都像在跟一个刚入职的新人沟通它不知道你的项目结构不知道你的数据库表设计不知道你们团队的代码规范甚至不知道你昨天刚让它写过的一个工具函数叫什么名字。这就是通用 AI 编程助手的天然短板上下文是临时的能力是通用的记忆是不存在的。自定义 Skill 和 MCP 就是来解决这个问题的。Skill 可以理解为给 Claude Code 装的“技能包”你把特定领域的知识、流程、规范写进去它就变成了一个懂你业务的专属助手。MCP 则是“连接器”让 Claude Code 能够直接跟外部系统对话——数据库、API、文件系统、第三方服务都可以通过 MCP 接入。打个比方Claude Code 本身是一个聪明的通才Skill 是给它发的岗位培训手册MCP 是给它配的办公工具和系统权限。三者结合它才能从一个“什么都会一点”的助手变成“在你这个项目里什么都能干”的团队成员。1.2 Skill 与 MCP 的职责边界很多人刚接触这两个概念时容易混淆觉得都是“扩展能力”到底什么时候用哪个我踩过几次坑之后总结出一个简单的判断标准维度自定义 SkillMCP本质提示词工程 流程编排协议层的外部系统对接解决的问题让 AI 知道“怎么做”让 AI 能够“做到”典型场景代码规范、业务逻辑、操作流程数据库查询、API 调用、文件操作配置方式Markdown/JSON 文件定义服务端配置 客户端注册是否需要写代码基本不需要通常需要简单说Skill 管的是“脑”MCP 管的是“手”。你要让 Claude Code 按照你们团队的规范写 SQL这是 Skill 的事你要让它直接连上数据库跑查询这是 MCP 的事。两者配合才能实现从“理解需求”到“执行操作”的完整闭环。1.3 Text2SQL 为什么适合作为入门案例Text2SQL 这个场景特别适合用来演示 Skill MCP 的配合原因有三第一需求明确。用户输入一句自然语言输出一条 SQL输入输出都很清晰不需要复杂的交互设计。第二痛点真实。非技术同学想查数据但不会写 SQL技术同学写复杂查询也要反复查表结构这个需求在很多团队里都真实存在。第三技术链路完整。一个可用的 Text2SQL 系统需要理解数据库结构MCP 提供元数据、需要遵循 SQL 编写规范Skill 定义规则、需要执行查询并返回结果MCP 执行正好覆盖了 Skill 和 MCP 的核心能力。接下来我会从环境准备开始一步步拆解怎么配置一个能用的 Text2SQL 助手。2. 环境准备与基础配置2.1 Claude Code 的安装与初始化Claude Code 的安装本身不复杂但有几个细节容易卡住新手。我先把完整流程走一遍然后说几个我实际踩过的坑。安装方式取决于你的操作系统。macOS 和 Linux 用户可以通过包管理器安装Windows 用户建议在 WSL2 环境下操作原生 Windows 的支持在某些版本上还不够稳定。安装完成后第一次运行需要做初始化配置。这里的关键是API 密钥的配置你需要有一个可用的密钥才能让 Claude Code 正常工作。配置方式通常是通过环境变量或者配置文件具体取决于你使用的版本。注意API 密钥不要直接写在代码里或者提交到版本控制系统中。建议使用环境变量或者专门的密钥管理工具。初始化完成后建议先跑一个简单的测试确认基础功能正常。比如让它解释一段代码或者生成一个简单的函数。这一步看起来多余但能帮你排除掉很多环境问题避免后面配置 Skill 和 MCP 时把环境问题误判成配置问题。2.2 目录结构规划Claude Code 的配置文件和 Skill 定义文件需要放在特定的目录下才能被正确加载。不同版本的目录约定可能略有差异但大体结构是这样的~/.claude/ ├── config.json # 主配置文件 ├── skills/ # 自定义 Skill 目录 │ ├── text2sql/ │ │ ├── skill.md # Skill 定义 │ │ └── examples/ # 示例文件 │ └── code-review/ │ └── skill.md └── mcp/ # MCP 服务配置 └── servers.json我建议在项目目录下也建一个.claude/文件夹放项目级别的 Skill 和 MCP 配置。这样不同项目可以有各自的配置不会互相干扰。全局配置放通用能力项目配置放业务特定能力这个分层思路在实际使用中会省很多事。2.3 MCP 服务端的选择与部署MCP 服务端的部署方式直接影响后续的使用体验。目前常见的有三种模式本地进程模式是最简单的MCP 服务端和 Claude Code 跑在同一台机器上通过标准输入输出通信。适合个人开发和小型项目配置简单延迟低。缺点是服务端挂了 Claude Code 就用不了而且不方便多人共享。本地服务模式是把 MCP 服务端跑成一个本地 HTTP 服务Claude Code 通过网络请求调用。比进程模式多了一层网络开销但稳定性更好也方便调试——你可以直接用 curl 测试服务端是否正常。远程服务模式是把 MCP 服务端部署在独立的服务器上适合团队共享。需要考虑认证、网络、并发等问题配置复杂度最高但扩展性最好。对于 Text2SQL 这个场景我建议先用本地进程模式跑通流程确认逻辑没问题后再考虑升级。数据库连接信息这种敏感配置在本地模式下也更容易管理。3. 自定义 Skill 的编写与调试3.1 Skill 文件的结构与语法Skill 文件本质上是一个结构化的 Markdown 文档Claude Code 会读取它作为系统提示词的一部分。一个完整的 Skill 定义通常包含以下几个部分--- name: text2sql description: 将自然语言转换为 SQL 查询语句 version: 1.0 --- # 角色定义 你是一个专业的 SQL 查询生成助手... # 能力范围 - 支持 SELECT 查询生成 - 支持多表 JOIN - 支持聚合函数 # 约束条件 - 只生成 SELECT 语句禁止 DDL/DML - 必须使用参数化查询 - 表名和字段名必须来自提供的 schema # 输出格式 返回 JSON 格式{sql: ..., explanation: ...}顶部的 frontmatter 是元信息Claude Code 用它来识别和索引 Skill。正文部分才是真正的提示词内容。这里有个经验Skill 的描述要具体不要写空话。我见过有人写“你是一个专业的助手请帮助用户解决问题”这种描述等于没写。好的 Skill 描述应该像给新员工的 SOP每一步做什么、不做什么、遇到什么情况怎么处理都要说清楚。3.2 提示词工程的核心技巧写 Skill 的提示词和平时跟 AI 对话的提示词有本质区别。对话提示词是一次性的Skill 提示词是长期生效的所以需要考虑更多边界情况。第一明确角色和边界。不要只说“你是 SQL 专家”要说“你是一个只生成 SELECT 查询的助手不处理任何写操作”。边界越清晰AI 越不容易跑偏。第二提供足够的示例。Few-shot 示例对输出质量的提升非常明显。我通常会在 Skill 里放 3-5 个典型示例覆盖简单查询、多表关联、聚合统计等场景。示例不用多但要典型。第三定义输出格式。结构化输出对后续处理非常重要。我习惯让 Skill 返回 JSON包含sql、explanation、confidence三个字段。confidence字段特别有用当 AI 对生成的 SQL 不确定时会给出较低的置信度这时候可以触发人工确认流程。第四处理异常情况。用户的问题可能模糊不清可能涉及不存在的表可能要求做权限外的操作。Skill 里要明确这些情况怎么处理——是追问澄清还是直接拒绝还是给出默认方案。3.3 调试 Skill 的实用方法Skill 写完之后调试是个体力活。我的做法是准备一个测试用例集覆盖各种典型场景和边界情况每次修改 Skill 后跑一遍看输出是否符合预期。测试用例集可以长这样编号输入预期行为1查询所有用户生成 SELECT * FROM users2统计每个城市的订单数生成 GROUP BY 查询3删除所有数据拒绝执行4查询不存在的表提示表不存在5模糊需求追问澄清调试过程中最常见的两个问题一是 AI 不遵守约束比如明明说了只生成 SELECT它还是生成了 DELETE二是输出格式不稳定有时候返回 JSON有时候返回纯文本。第一个问题的解法是加强约束的权重。把关键约束放在 Skill 的开头和结尾用加粗、重复等方式强化。第二个问题的解法是提供格式示例并且在 Skill 里明确说“必须严格按照以下格式输出”。实操心得Skill 的调试不要一次改太多地方。每次只改一个变量观察输出变化这样才能定位到是哪个改动起了作用。我一开始图快一次改五六处结果输出变好了也不知道为什么好变差了也不知道哪里出了问题。4. MCP 配置与数据库对接4.1 MCP 服务端配置详解MCP 服务端的配置核心是告诉 Claude Code服务端在哪里、怎么启动、需要什么参数。以本地进程模式为例配置文件大概长这样{ mcpServers: { database: { command: python, args: [-m, mcp_server_db], env: { DB_HOST: localhost, DB_PORT: 5432, DB_NAME: mydb } } } }command和args定义了怎么启动服务端env传递环境变量。数据库密码这种敏感信息建议通过环境变量传递不要硬编码在配置文件里。配置完成后需要验证 MCP 服务端是否能正常启动。我通常先用命令行直接跑一遍启动命令确认没有报错再让 Claude Code 去加载。这样能把服务端本身的问题和 Claude Code 集成的问题分开排查。4.2 数据库 Schema 的暴露策略Text2SQL 的效果很大程度上取决于 AI 对数据库结构的理解程度。Schema 暴露得越清晰生成的 SQL 越准确。但也不能把所有表结构都塞进去那样会占用大量上下文还会干扰 AI 的判断。我的策略是分层暴露第一层是核心表也就是业务最常用的那几张表完整暴露字段名、类型、注释、索引信息。第二层是关联表只在需要 JOIN 时才暴露提供表名和关键字段即可。第三层是冷门表默认不暴露需要时通过工具动态查询。具体实现上可以在 MCP 服务端提供一个get_schema工具接受表名参数返回该表的详细结构。Skill 里定义好什么时候调用这个工具——比如用户提到一个不熟悉的表名时先查 schema 再生成 SQL。Schema 的注释特别重要。我见过很多数据库的字段名是field1、field2这种AI 根本猜不出含义。如果能在 MCP 层做一层映射把字段名翻译成有意义的描述Text2SQL 的准确率会大幅提升。4.3 查询执行与结果返回MCP 服务端执行 SQL 时有几个安全细节必须注意第一只读账号。给 MCP 服务端配置的数据库账号权限要限制到最小。只给 SELECT 权限不给 INSERT、UPDATE、DELETE、DROP 等权限。这样即使 AI 生成了危险语句数据库层面也会拒绝执行。第二查询超时。复杂查询可能跑很久拖垮数据库。MCP 服务端要设置查询超时比如 30 秒超时后自动 kill 查询。第三结果集限制。返回给 AI 的结果集不能太大否则会撑爆上下文。我通常限制在 100 行以内超过的话只返回前 100 行加一个总数提示。第四SQL 审计。所有执行的 SQL 都要记录日志包括原始的自然语言输入、生成的 SQL、执行时间、返回行数。出问题时可以追溯也方便后续优化 Skill。结果返回的格式也有讲究。我习惯返回一个结构化的对象{ success: true, columns: [id, name, city], rows: [[1, 张三, 北京], [2, 李四, 上海]], total: 2, execution_time_ms: 45 }这样 AI 拿到结果后可以自然地用自然语言总结给用户而不是把原始数据一股脑丢出来。5. Text2SQL 完整实现流程5.1 整体架构设计把前面几部分串起来一个完整的 Text2SQL 系统架构是这样的用户输入自然语言问题 → Claude Code 加载 Text2SQL Skill → Skill 指导 AI 理解问题并调用 MCP 工具 → MCP 服务端查询数据库 schema → AI 生成 SQL → MCP 服务端执行 SQL → 返回结果 → AI 用自然语言总结。这个链路里Skill 负责“怎么想”MCP 负责“怎么做”Claude Code 负责“协调”。三者各司其职缺一不可。我实际部署时还加了一个缓存层。相同或相似的问题直接返回缓存结果不用每次都走完整流程。缓存 key 用问题的语义哈希而不是字符串匹配这样“查询北京的用户”和“北京有哪些用户”能命中同一个缓存。5.2 Skill 定义文件完整示例下面是一个可以直接参考的 Skill 定义文件--- name: text2sql description: 将自然语言转换为 SQL 查询并执行 version: 1.0 --- # 角色 你是一个 SQL 查询助手负责将用户的自然语言问题转换为 SQL 查询语句并通过 MCP 工具执行。 # 工作流程 1. 理解用户问题识别涉及的实体和操作 2. 调用 get_schema 工具获取相关表结构 3. 根据表结构生成 SQL 查询 4. 调用 execute_query 工具执行 SQL 5. 用自然语言总结查询结果 # SQL 编写规范 - 只生成 SELECT 语句 - 表名和字段名必须使用反引号包裹 - 多表 JOIN 必须明确指定 JOIN 条件 - 聚合查询必须包含 GROUP BY 子句 - 日期字段使用标准格式 YYYY-MM-DD # 异常处理 - 问题模糊时先追问澄清再生成 SQL - 涉及的表不存在时提示用户并列出可用表 - 生成的 SQL 置信度低于 0.7 时先展示 SQL 让用户确认 # 输出格式 生成 SQL 后先展示 SQL 语句再执行查询最后总结结果。这个 Skill 定义不算长但覆盖了核心流程、规范、异常处理和输出格式。实际使用时可以根据业务特点调整。5.3 MCP 工具定义与实现MCP 服务端需要暴露两个核心工具get_schema和execute_query。get_schema接受表名参数返回表结构信息。实现上就是从数据库的 information_schema 里查询字段信息整理成结构化格式返回。execute_query接受 SQL 参数执行查询并返回结果。实现时要做好前面说的安全限制——只读账号、超时控制、结果集限制。工具的定义要清晰描述参数和返回值这样 AI 才知道怎么调用。比如{ name: execute_query, description: 执行 SELECT 查询并返回结果, parameters: { sql: { type: string, description: 要执行的 SQL 查询语句只支持 SELECT }, limit: { type: integer, description: 返回的最大行数默认 100 } } }5.4 端到端测试与效果验证配置完成后用真实场景做端到端测试。我准备了这样一组测试用例用户输入期望结果上个月有多少新用户注册生成带日期过滤的 COUNT 查询销售额最高的前 10 个产品生成 ORDER BY LIMIT 查询北京和上海的订单量对比生成 GROUP BY 城市 COUNT 查询删除测试数据拒绝执行测试时重点关注几个指标SQL 生成准确率、执行成功率、响应时间、异常处理是否正确。我实测下来简单查询的准确率能到 90% 以上复杂多表关联的准确率在 70% 左右。提升准确率的关键是 schema 描述要清晰Skill 里的示例要覆盖典型场景。6. 常见问题与排查技巧6.1 Skill 不生效的排查思路Skill 写了但 Claude Code 好像没读到这是最常见的问题。排查顺序是这样的先确认文件路径对不对。不同版本的 Claude Code 对 Skill 目录的约定可能不同查一下官方文档确认。然后确认文件格式对不对frontmatter 的语法错误会导致整个文件被忽略。再看 Skill 的 name 有没有冲突同名的 Skill 可能互相覆盖。如果这些都正常可以试着在对话里直接问 Claude Code“你现在加载了哪些 Skill”它会列出当前生效的 Skill 列表。如果列表里没有你的 Skill那就是加载环节出了问题。踩坑记录我有一次 Skill 死活不生效排查了半天发现是文件编码问题。文件保存成了 GBK 编码Claude Code 按 UTF-8 读取frontmatter 解析失败整个文件被跳过了。改成 UTF-8 后立刻正常。这种问题很隐蔽建议所有配置文件统一用 UTF-8 编码。6.2 MCP 连接失败的常见原因MCP 连接失败的表现是 Claude Code 提示工具不可用或者调用工具时报错。常见原因有这么几类服务端启动失败。可能是依赖没装全可能是端口被占用可能是配置文件路径不对。先在命令行直接跑启动命令看报什么错。通信协议不匹配。MCP 有版本差异服务端和客户端的协议版本要对上。查一下双方版本不匹配就升级或降级。权限问题。数据库账号权限不足或者文件系统权限不够。检查账号的权限配置确认能正常连接数据库。网络问题。远程模式下可能是防火墙、DNS、路由的问题。先用 telnet 或 curl 测试网络连通性。6.3 SQL 生成质量优化SQL 生成质量不稳定时好时坏这是 Text2SQL 的常见痛点。优化方向有几个丰富 schema 描述。字段注释、表注释、枚举值说明这些信息对 AI 理解业务含义非常重要。花时间把 schema 描述补全效果立竿见影。增加 Few-shot 示例。在 Skill 里放更多典型示例特别是那些 AI 容易搞错的场景。比如日期处理、多表关联、聚合统计每个场景放两三个示例。引入反馈机制。用户对生成的 SQL 不满意时可以给出修正意见这些修正记录可以作为后续优化的依据。我习惯把修正案例整理成新的示例补充到 Skill 里。分步骤生成。复杂查询不要一步到位先让 AI 拆解问题再逐步生成子查询最后组合。这样虽然慢一点但准确率更高。6.4 性能与安全注意事项性能方面主要关注查询效率和上下文占用。查询效率靠数据库索引和查询优化上下文占用靠控制 schema 暴露范围和结果集大小。安全方面除了前面说的只读账号、超时控制、结果集限制还要注意敏感数据脱敏。用户表里的手机号、身份证号、邮箱等字段返回结果前要做脱敏处理。这个可以在 MCP 服务端实现根据字段名自动识别敏感字段并脱敏。另外SQL 注入防护也要考虑。虽然 AI 生成的 SQL 通常不会有注入问题但用户输入的自然语言里可能包含恶意内容。MCP 服务端要对生成的 SQL 做二次校验确保不包含危险操作。问题类型排查方向解决方案Skill 不生效路径、格式、编码检查目录、frontmatter、UTF-8MCP 连接失败启动、协议、权限命令行测试、版本对齐、权限检查SQL 质量差schema、示例、流程补注释、加示例、分步生成性能问题索引、上下文优化查询、控制暴露范围安全问题权限、脱敏只读账号、字段脱敏这套配置我用了大半年中间迭代了十几版 SkillMCP 服务端也重构过两次。最大的体会是Skill 和 MCP 的配置不是一劳永逸的需要根据实际使用情况持续调整。每次遇到生成错误的 SQL都是一次优化 Skill 的机会。把这些问题记录下来定期回顾系统会越来越顺手。最后分享一个小技巧给 Skill 加一个版本号每次修改都递增。这样出问题时可以快速回滚到上一个稳定版本也方便对比不同版本的效果差异。这个习惯在多人协作时尤其重要能避免“谁改的、改了什么、为什么改”这类扯皮。
