# How the SQL Query Generation Skill Works in PM Skills: Mechanism and Architecture > Discover the SQL query generation skill in PM Skills. Learn how this markdown-defined pipeline transforms natural language into optimized SQL using LLM for efficient data requests. - Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills) - Tags: internals - Published: 2026-07-10 --- **The SQL query generation skill in PM Skills operates as a deterministic four-step pipeline defined entirely in markdown, using the LLM to transform natural language requests and schema context into optimized, dialect-specific SQL statements.** The **SQL query generation skill** (identified as `sql-queries`) is a core capability within the `phuryn/pm-skills` repository’s data analytics module. Unlike traditional code-based implementations, this skill leverages a structured markdown specification to orchestrate the LLM through a precise workflow, enabling the generation of production-ready SQL for multiple database dialects including BigQuery, PostgreSQL, MySQL, and Snowflake. ## The Four-Step Mechanism The skill’s behavior is defined in [`pm-data-analytics/skills/sql-queries/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-data-analytics/skills/sql-queries/SKILL.md), which implements a rigid four-phase pipeline to ensure accurate query construction. ### Schema Ingestion When a user provides database context, the skill first parses the input to extract structural metadata. This includes identifying **table names**, **column definitions**, **data types**, **primary and foreign keys**, and **indexes** from uploaded SQL DDL files, documentation, or textual diagram descriptions. This ingestion phase creates a concrete semantic model that grounds the LLM’s subsequent reasoning in the actual database structure rather than assumptions. ### Request Clarification Before generating code, the skill engages the user to specify the **target SQL dialect** and precise data requirements. The LLM prompts for clarification on filters, aggregations, sorting criteria, and any performance constraints. This step ensures the generated query aligns with both the semantic intent and the technical limitations of the specific database engine. ### Query Generation Using the extracted schema and clarified requirements, the LLM constructs an optimized SQL statement. The skill instructs the model to include **inline comments**, **performance optimization tips**, and **alternative approaches** where appropriate. The output is tailored to the specified dialect, handling syntax variations between BigQuery’s Standard SQL, PostgreSQL’s procedural extensions, or MySQL’s specific functions. ### Explanation & Validation The final phase delivers more than raw SQL. The skill generates a **plain-English explanation** of the query logic, provides **suggestions for testing** the statement against real data, and optionally includes **sample test scripts** or validation queries. This ensures the output is immediately actionable and verifiable by the user. ## Key Source Files and Architecture The SQL query generation capability is implemented through three critical files that define its behavior and integration: - **[`pm-data-analytics/skills/sql-queries/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-data-analytics/skills/sql-queries/SKILL.md)** – The primary skill definition containing the four-step workflow, prompt templates, and dialect-specific instructions. - **[`pm-data-analytics/commands/write-query.md`](https://github.com/phuryn/pm-skills/blob/main/pm-data-analytics/commands/write-query.md)** – The command interface that triggers the `sql-queries` skill when users invoke the "Write Query" action. - **[`pm-data-analytics/.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/pm-data-analytics/.claude-plugin/plugin.json)** – The plugin metadata that registers the `pm-data-analytics` bundle, exposing the SQL skill to the Claude engine. No additional Python or JavaScript code is required to execute this skill. The mechanism relies entirely on the markdown specification and the underlying LLM’s ability to interpret the structured prompts defined in [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md). ## Practical Examples of SQL Generation The following examples demonstrate how the skill processes different input types through the four-step mechanism. **Example 1: DDL Schema Ingestion** When provided with a schema file, the skill parses the structure before generating the query: ```text Upload: database_schema.sql Prompt: "Generate a query to find users who signed up in the last 30 days and had at least 5 active sessions." ``` The skill returns a dialect-appropriate SQL statement with comments explaining the join logic between users and sessions tables, along with performance notes regarding index usage on date columns. **Example 2: Textual Schema Description** For informal schema descriptions, the skill extracts entities and relationships before generation: ```text Prompt: "Here's my DB: Users(id, email, created_at), Sessions(id, user_id, timestamp, duration). Generate a query for average session duration per user in January 2026." ``` The output includes a `SELECT` statement with proper date filtering, aggregation functions, and grouping clauses specific to the requested dialect. **Example 3: Complex BigQuery Analytics** For advanced analytical queries, the skill handles window functions and CTEs: ```text Prompt: "Create a BigQuery query to analyse revenue by region and customer tier, including YoY growth." ``` The generated SQL utilizes BigQuery-specific syntax for analytical window functions, handling partition clauses and year-over-year calculations with `LAG()` or `LEAD()` functions as appropriate. ## Summary - The **SQL query generation skill** operates through a **four-step pipeline**: Schema Ingestion, Request Clarification, Query Generation, and Explanation & Validation. - The entire mechanism is defined in **[`pm-data-analytics/skills/sql-queries/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-data-analytics/skills/sql-queries/SKILL.md)** with no custom code required. - The skill supports **multiple SQL dialects** including BigQuery, PostgreSQL, MySQL, and Snowflake through dialect-specific prompting. - Execution is triggered via **[`pm-data-analytics/commands/write-query.md`](https://github.com/phuryn/pm-skills/blob/main/pm-data-analytics/commands/write-query.md)**, which applies the `sql-queries` skill to user requests. - Output includes **optimized SQL**, **plain-English explanations**, and **testing recommendations** rather than just raw code. ## Frequently Asked Questions ### What file defines the SQL query generation behavior in PM Skills? The behavior is entirely defined in [`pm-data-analytics/skills/sql-queries/SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/pm-data-analytics/skills/sql-queries/SKILL.md). This markdown file contains the step-by-step workflow, prompt templates, and instructions that guide the LLM through schema ingestion, clarification, generation, and explanation phases. ### How does the skill handle different SQL dialects? During the **Request Clarification** step, the skill explicitly prompts the user to specify the target database engine. The prompt templates in [`SKILL.md`](https://github.com/phuryn/pm-skills/blob/main/SKILL.md) include dialect-specific instructions that guide the LLM to use appropriate syntax for BigQuery, PostgreSQL, MySQL, Snowflake, or other supported systems. ### Can the skill generate queries without a provided schema? Yes. While the **Schema Ingestion** step enhances accuracy by parsing DDL files or schema descriptions, the skill can operate on textual descriptions of tables and relationships. The LLM will request clarification about table structures if the initial prompt provides insufficient detail for accurate query construction. ### Where is the Write Query command defined? The command is defined in [`pm-data-analytics/commands/write-query.md`](https://github.com/phuryn/pm-skills/blob/main/pm-data-analytics/commands/write-query.md). This file serves as the interface that invokes the `sql-queries` skill, allowing users to trigger the four-step generation pipeline through the PM Skills plugin architecture registered in [`pm-data-analytics/.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/pm-data-analytics/.claude-plugin/plugin.json).