SQL Generator

---
name: sql-gen
description: >
  Generate SQL from a natural-language description of a query or report.
  Produces dialect-correct statements (PostgreSQL, MySQL, SQLite, BigQuery,
  Snowflake) plus a short explanation of how the query works and any
  indexes that would speed it up. Use to unblock product/analyst requests
  without hand-writing joins, to prototype a dashboard query, or to
  reverse-engineer a legacy report into a clean CTE.
when-to-use:
  - Turning a product question into a query
  - Drafting a CTE for a recurring report
  - Converting a Google Sheets formula into a database query
  - Migrating a query between SQL dialects
---

# SQL Generator

Describe what you want in plain English (or paste a rough sketch) and get
a clean, dialect-correct query back.

## Overview

The skill takes a natural-language prompt, an optional schema description,
and an optional dialect, then emits SQL that:

- Uses modern constructs (CTEs, window functions, `LATERAL` joins) when
  they improve readability.
- Quotes every identifier, parameterizes every literal that contains
  user-controlled data.
- Carries a one-paragraph "how it works" explanation above the query.
- Lists suggested indexes at the bottom if the row count is large.

If the prompt is ambiguous (e.g. "top customers"), the skill asks a single
clarifying question rather than guessing silently.

## Usage examples

```bash
# Generate a query against an explicit schema
npx skills run sql-gen \
  --schema schema.sql \
  --prompt "Monthly active users by plan for the last 6 months"

# Emit a Snowflake query with parameter placeholders
npx skills run sql-gen \
  --dialect snowflake \
  --prompt "Cohort retention by signup week" \
  --params ":start_date,:end_date"

# Convert an old MySQL query to Postgres
npx skills run sql-gen \
  --dialect postgres \
  --convert-from mysql < legacy.sql
```

## Parameters

| Name | Type | Default | Description |
|---|---|---|---|
| `prompt` | string | — | Natural-language request. |
| `schema` | string | auto-discovered | Path to a `.sql`/`.ddl` file or stdin. |
| `dialect` | enum | `postgres` | `postgres`, `mysql`, `sqlite`, `bigquery`, `snowflake`. |
| `params` | string[] | `[]` | Named placeholders the query should accept. |
| `convert_from` | enum | — | Translate from this dialect to `dialect`. |
| `explain` | bool | `true` | Include the "how it works" paragraph. |
| `limit` | int | `1000` | Add a `LIMIT`/`TOP` clause when `> 0`. |

## Expected output

A Markdown or JSON block with `query`, `explanation`, `params`, and
`indexes`. When `params` is non-empty, the query uses those names instead
of inline literals so the caller can pass them safely.