前言¶
产品、运营、分析师经常需要临时取数，但表结构、方言和 JOIN 写法并不熟悉；把需求交给开发排队，往往要等半天。自己在文档里拼 SQL，又容易漏条件或写错字段。下面介绍 SkillHub 上的社区 Skill「SQL查询助手」：它在 Agent 对话里按固定流程把自然语言转成可执行的 SQL，并补充逻辑解释与优化建议；它不连库、不执行语句，适合「先写出对的 SQL，再到自己的客户端里跑」这类工作流。
这是什么¶
「SQL查询助手」是遵循通用 SKILL.md 格式的 Agent Skill，坐标为 @user_70c2f807/sql-query-assistant，当前版本 1.0.0，来源为 community，分类 dev-programming，由发布者 user_70c2f807 维护。SkillHub 页面标注 requires_api_key=false，安装后无需额外 API Key。
官方入口：
- API 坐标页：https://api.skillhub.cn/user_70c2f807/sql-query-assistant
- SkillHub 展示页：https://www.skillhub.cn/skills/user_70c2f807/sql-query-assistant
Skill 文档中的定位是：将自然语言转化为 SQL，附带执行逻辑说明和优化建议，缓解「每次取数都要等开发」的协作成本。明确不适用于数据库设计、数据库运维、ORM 编程、数据仓库建模等场景。
核心功能¶
以下能力均来自 Skill 包内 SKILL.md，安装后即可被 Agent 按说明触发与执行。
- 自然语言转 SQL：支持
SELECT、JOIN、子查询、窗口函数等常见写法。 - 解释已有 SQL：按步骤说明查询在做什么。
- 性能与优化建议：在用户反馈慢查询时，分析瓶颈并给出索引或改写思路。
- 多方言：文档写明支持 MySQL、PostgreSQL、SQL Server、Hive；使用前需说明实际数据库，避免函数与日期语法混用。
- 验证与模板：可生成测试数据思路、常见业务场景模板（如留存、转化、排行榜等，以文档列举为准）。
触发与边界（文档原文要点）：当用户提到 SQL 查询、取数、写 SQL、sql query、database query 等意图时启用；不执行 SQL，只输出语句与说明；需要表结构信息（表名、字段或数据形态描述）；复杂查询在生产环境执行前建议由 DBA 审核。
安装与启用¶
安装 SkillHub CLI¶
若本机尚未安装 skillhub，可先按官方安装说明检查或安装 CLI：
command -v skillhub && skillhub --version
未安装时，完整安装（CLI + 默认 Skill）可使用：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
仅安装 CLI：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only
说明来源：https://skillhub.cn/install/skillhub.md
安装 SQL查询助手¶
搜索确认坐标后，将 Skill 安装到当前 Agent 的 skills 目录（--dir 必须指向会被客户端加载的路径，否则默认落在 ./skills/ 可能无法识别）：
skillhub search sql-query-assistant
skillhub install sql-query-assistant --namespace user_70c2f807 --dir ~/.cursor/skills/
也可使用坐标形式（示例与 SkillHub 页面提示一致）：
skillhub install @user_70c2f807/sql-query-assistant --dir ~/.cursor/skills/
Cursor：skills 目录为 ~/.cursor/skills/（见 SkillHub 安装文档「常用 AI Client 的 Skills 路径」）。
Claude Code：同一文档列出 ~/.claude/skills/。
Codex：文档列出 ~/.codex/skills/ 或项目下的 .agents/skills/。
安装完成后，按你所用客户端的要求重启或刷新 Agent，使新 Skill 被加载。SkillHub 页面亦支持将「请根据 https://skillhub.cn/install/skillhub.md，安装 @user_70c2f807/sql-query-assistant」发给 AI，由 Agent 按文档完成安装。
典型用法¶
Skill 文档给出了对话式流程，下面是可以直接复现的交互顺序。
1. 从零写查询
用户说明目标后，Agent 会先对齐表与条件；例如需求为「查最近 30 天每日新增用户数」，应得到完整 SQL、逻辑解释和注意事项。
2. 在已有 SQL 上迭代
用户说「再加上按渠道分组」，Agent 应在原查询上补充 GROUP BY 等子句，而不是另起一套无关语句。
3. 慢查询优化
用户反馈「这个 SQL 跑了 10 分钟，能优化吗？」时，Agent 应结合已提供的 SQL 与表结构，给出索引与改写建议，并提醒大表、去重聚合等风险点。
4. 读懂他人写的 SQL
用户请求「帮我把这个 SQL 解释一下」，Agent 应逐段说明各子句作用。
文档建议的输出结构包括：需求摘要、数据库类型、SQL 代码块、分步逻辑说明、预期结果示例、注意事项与优化建议。实际对话中不必强求装饰性排版，但应保证 SQL 可复制、关键语句有中文注释，并默认避免未经确认的 DELETE / UPDATE / DROP 等破坏性语句。
当缺少表结构时，Skill 约定提示用户提供表名与字段，或先执行 SHOW TABLES、DESCRIBE 表名 再继续。
适用场景与注意¶
适合谁
- 需要自助取数、但 SQL 不熟练的产品、运营、分析师。
- 能在对话中补充表结构、筛选条件与数据库类型的开发者。
- 希望 Agent 统一产出「SQL + 解释 + 优化提示」，而不是只给一段裸语句的团队。
限制与坑
| 点 | 说明 |
|---|---|
| 不连库 | 只生成 SQL，执行与权限由用户在自有工具中完成。 |
| 表结构 | 无 DDL 或字段说明时，生成结果容易偏离真实 schema。 |
| 方言 | 必须声明 MySQL / PostgreSQL / SQL Server 等，避免日期函数、引号规则混用。 |
| 性能 | 文档不保证生产性能；大表或复杂聚合应经 DBA 审核。 |
| 范围 | 数据库设计、运维、ETL 调度、NoSQL 查询不在 Skill 设计范围内。 |
SkillHub 统计（以抓取资料为准）：评分 100000，下载 984，标签 requires_api_key=false。社区 Skill 会随发布者更新，使用前可在 SkillHub 页面核对版本 1.0.0 是否与本地一致。
结尾¶
「SQL查询助手」把取数需求收敛成可复制的 SQL 和可读的解释，适合在 Agent 里做「写查询、改查询、读查询、谈优化」四类事；它替代的不是数据库客户端，而是反复口述需求、手工查语法的碎片时间。需要安装或查看元数据时，请打开官方页：https://www.skillhub.cn/skills/user_70c2f807/sql-query-assistant 。
