How the SQL Query Generation Skill Works in PM Skills: Mechanism and Architecture

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, 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 – The primary skill definition containing the four-step workflow, prompt templates, and dialect-specific instructions.
• 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 – 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.

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:

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:

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:

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 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, 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. 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}