pm-skills 之 sql-queries 技能实战：让 AI 把自然语言需求直接变成可用的多方言 SQL

pm-skills 之 sql-queries 技能实战：让 AI 把自然语言需求直接变成可用的多方言 SQL

【免费下载链接】pm-skillsPM Skills Marketplace: 100+ agentic skills, commands, and plugins — from discovery to strategy, execution, launch, and growth.项目地址: https://gitcode.com/GitHub_Trending/pm/pm-skills

本篇文章以 pm-skills 仓库中pm-data-analytics插件的sql-queries 技能（SKILL.md）为核心，系统讲解如何让 AI 将产品经理、分析师和工程师的自然语言数据需求，自动转化为可运行、可优化的 SQL 查询，覆盖 BigQuery、PostgreSQL、MySQL、Snowflake、SQL Server 等多种方言。读完本文，你将掌握该技能的四步工作流、三种典型用法、核心能力边界与输出规范，并理解它与/write-query命令的联动关系以及仓库底层对技能元数据的校验机制。

技能定位：pm-data-analytics 插件的三大数据分析能力之一

在 pm-skills 仓库中，pm-data-analytics插件（插件 README）面向产品经理的数据分析场景，共提供 3 个技能与 3 个命令。sql-queries正是其中的自然语言转 SQL 技能，与cohort-analysis（SKILL.md）、ab-test-analysis（SKILL.md）共同构成完整的数据分析闭环——先用 SQL 取数，再做留存与 A/B 分析。

根据 CLAUDE.md 中定义的设计规则（CLAUDE.md）：

• 技能 = 名词/概念：sql-queries属于"框架与领域知识"类技能，对话话题匹配时会由 Claude 自动加载，无需显式调用；
• 命令 = 动词：/write-query（write-query.md）是用户主动触发的端到端工作流，内部通过Apply the **sql-queries** skill的方式调用该技能。

技能元数据（frontmatter）中name必须与目录名一致（sql-queries），description必须包含触发短语（如 "Use when writing SQL"），这些约束由仓库根目录的 validate_plugins.py 自动校验，确保技能能被正确发现与加载。

核心能力总览：从自然语言到优化查询的完整映射

该技能的核心目标只有一个：把自然语言需求转化为跨多种数据库平台的优化 SQL 查询。它面向三类人群——产品经理（验证业务假设）、分析师（快速出数）、工程师（省去手工写语法），帮助用户在不手工纠结 SQL 语法的情况下拿到准确的查询结果。

技能 frontmatter 中的描述精准定义了它的适用边界（SKILL.md）：

Generate SQL queries from natural language descriptions. Supports BigQuery, PostgreSQL, MySQL, and other dialects. Reads database schemas from uploaded diagrams or documentation.Use when writing SQL, building data reports, exploring databases, or translating business questions into queries.

即：写 SQL、构建数据报表、探索数据库、把业务问题翻译成查询语句——这四类场景都是该技能的触发时机。

四步工作流详解

技能的正文主体是一套固定的四步工作流，每一步都有明确的输入、处理动作与产出。下面结合仓库源码与实际操作逐步展开。

Step 1：理解你的数据库 Schema

当用户提供 schema 文件（SQL、文档或图表描述）时，AI 会读取并分析它，依次完成：

• 提取表名（table names）；
• 提取列定义（column definitions）；
• 识别数据类型（data types）；
• 梳理表与表之间的关系（relationships）；
• 定位主键（primary keys）、外键（foreign keys）；
• 评估索引策略（indexing strategies）。

这一步骤是整个流程的地基：schema 越完整，后续生成的查询就越能准确命中正确的表与列，避免 AI 凭 SaaS 通用模型臆测表结构。

Step 2：处理你的请求

在拿到 schema 之后，AI 会与用户对齐三个关键信息：

1. 澄清需求：确认你到底需要检索或分析哪些数据；
2. 确认方言：明确目标数据库类型——BigQuery、PostgreSQL、MySQL、Snowflake 等；
3. 补齐附加要求：是否需要过滤器（filters）、聚合（aggregations）、排序（sorting）等。

若用户没有提供 schema，/write-query命令文档（write-query.md）补充了回退策略：询问数据库类型 → 从问题推断合理 schema 并请用户确认 → 默认采用常见 SaaS 数据模型约定。

Step 3：生成优化查询

这是产出核心 SQL 的阶段，技能要求 AI 遵循四项质量准则：

• 编写高效 SQL，充分利用已掌握的数据库结构（正确的 join 路径、可用的索引）；
• 为复杂逻辑添加注释——因为 PM 会把查询分享给分析师，注释承载"意图"；
• 针对大数据集给出性能考量（分区、索引、避免全表扫描等）；
• 在适用时提供备选方案（alternative approaches）。

/write-query命令在此基础上进一步固化了工程规范（write-query.md）：复杂查询优先用CTE（公共表表达式）提升可读性而非嵌套子查询；必须处理边缘情况（NULL 值、时区问题、重复数据处理）；对可能在大数据集上变慢的查询主动标记并给出优化建议。

Step 4：解释与测试

生成查询后，技能要求 AI 完成收尾交付：

• 用通俗英语解释查询逻辑；
• 给出验证/测试建议（如何校验结果正确性）；
• 提供性能优化技巧；
• 用户有需要时，生成测试脚本或示例数据。

三种典型使用场景

原文档给出了三个从易到难的典型输入示例，覆盖了该技能最常见的三种用法：

场景一：基于上传的 Schema 文件生成查询

Upload your database_schema.sql file and say: "Generate a query to find users who signed up in the last 30 days and had at least 5 active sessions"

此时 AI 直接读取上传的database_schema.sql，无需额外确认表结构。示意性的产出可能形如：

-- 近 30 天注册、且活跃会话数 >= 5 的用户 SELECT u.id, u.email, u.created_at FROM users AS u JOIN ( SELECT user_id, COUNT(*) AS session_cnt FROM sessions WHERE timestamp >= CURRENT_DATE - INTERVAL '30 days' GROUP BY user_id HAVING COUNT(*) >= 5 ) AS s ON s.user_id = u.id WHERE u.created_at >= CURRENT_DATE - INTERVAL '30 days';

场景二：基于图表/文字描述的数据库结构生成查询

"Here's my database: Users table (id, email, created_at), Sessions table (id, user_id, timestamp, duration). Generate a query for average session duration per user in January 2026."

这是"无文件、纯描述"的典型路径——AI 从文字描述中直接提取表与列，完成 join 规划：

-- 2026 年 1 月每个用户的平均会话时长 SELECT u.id AS user_id, u.email, AVG(s.duration) AS avg_session_duration FROM users AS u JOIN sessions AS s ON s.user_id = u.id WHERE s.timestamp >= '2026-01-01' AND s.timestamp < '2026-02-01' GROUP BY u.id, u.email ORDER BY avg_session_duration DESC;

场景三：复杂分析查询（含聚合与时序对比）

"Create a BigQuery query to analyze our revenue by region and customer tier, including year-over-year growth rates."

这是多方言 + 复杂聚合的代表：需要 BigQuery 方言、多维度分组（region × customer tier）以及同比（YoY）增长率计算，通常需要借助窗口函数（LAG/PARTITION BY）或自连接实现。

六大核心能力矩阵

原文档用清单形式定义了技能的六项关键能力，这是衡量它"能干什么"的边界：

这六项能力在/write-query的产出模板中得到了结构化落地（write-query.md）：输出包含Dialect（方言）、Tables used（用到的表）、Query（带注释的 SQL 代码块）、What This Returns（返回结果的列与形状描述）、Assumptions（schema 假设与业务逻辑假设）、Notes（大数据集的性能考量与已处理/已标记的边缘情况）。

输出规范：一份查询交付物的完整结构

无论通过技能直接使用，还是经由/write-query命令，用户最终都会收到四层交付物：

1. SQL Query：带注释、可直接用于生产的 SQL 代码；
2. Explanation：查询做什么、如何工作的说明；
3. Performance Notes：优化提示与性能考量；
4. Test Script（按需）：示例数据与校验查询。

获得最佳效果的五条建议

原文档给出了五条输入侧的最佳实践，直接决定输出质量：

1. 提供上下文：分享你的数据库 schema 或结构——这是准确 join 的前提；
2. 描述具体：清晰说明你需要什么数据以及任何过滤器；
3. 指明数据库：指定你正在使用的 SQL 方言，避免方言误配；
4. 包含约束：说明数据量、时间范围与性能需求；
5. 要求格式：如需要特定输出结果格式，明确提出来。

/write-query命令在此基础上补了一条关键纪律（write-query.md）：如果请求存在歧义（例如 "active users"），必须请用户先精确定义指标，而不是擅自假设；同时，默认"可读优先于炫技"（CTE 优于嵌套子查询）。

仓库中的实现与规范依据

为了确保该技能在 Claude Code / Cowork 等 Agent 环境中被正确加载和执行，仓库通过 validate_plugins.py 施加了硬性约束：

• frontmatter 必填字段：技能必须包含name与description（validate_plugins.py），缺失会被判为 ERROR；
• name 与目录强一致：frontmatter 中的name必须等于所在目录名sql-queries（validate_plugins.py），违反即报错；
• description 质量门槛：长度过短（<30 字符）会告警，且建议包含触发短语（"use when"、"use for" 等）（validate_plugins.py），这正好对应 sql-queries frontmatter 中 "Use when writing SQL, ..." 的写法；
• 渐进式披露（progressive disclosure）：frontmatter 保持精简（始终加载），细节放在 SKILL.md 正文（触发时才加载）——这也是 CLAUDE.md 明确的设计原则。

从源码结构可以推断，这套"描述即触发词 + name 即目录名"的机制，是技能能被 Agent 自动发现和按需加载的底层保证：校验器保证元数据合规，而元数据保证运行时的正确触发。

从技能到命令：在 Claude Code 中实际使用

sql-queries 技能可以直接通过对话自然触发（话题匹配即自动加载），也可以强制加载（/pm-data-analytics:sql-queries或/sql-queries）。更常用的方式是调用封装好的/write-query命令（write-query.md）：

/write-query Show me daily active users for the last 30 days, broken down by plan tier /write-query Find users who signed up last month but never completed onboarding /write-query [upload a schema diagram] What's the conversion rate from trial to paid by cohort?

命令完成后还会提供后续动作建议，例如修改过滤器、调整分组、扩展时间范围、围绕查询构建仪表盘，或生成对应的 cohort 分析版本——与 analyze-cohorts.md 中的数据提取 SQL 形成闭环。整个pm-data-analytics插件可通过根目录 README.md 中的 Claude Code 安装方式引入：

claude plugin marketplace add phuryn/pm-skills claude plugin install pm-data-analytics@pm-skills

安装后，sql-queries技能与/write-query命令即可直接在对话中投入使用，将"业务问题 → 可执行 SQL"的翻译成本降到最低。

【免费下载链接】pm-skillsPM Skills Marketplace: 100+ agentic skills, commands, and plugins — from discovery to strategy, execution, launch, and growth.项目地址: https://gitcode.com/GitHub_Trending/pm/pm-skills