SQL Query Explainer skill for Claude and Codex

SQL Query Explainer as an AI skill. It asks for Query, Database, Table descriptions and 3 more, then does the rest. Free to install in Claude or Codex.

Install it once and Claude or Codex runs it for you. When your request matches, your AI loads the skill, asks for anything it is missing, and works through the template itself. Prefer to fill it in by hand? See the full prompt template.

Download the skill (.zip) · View SKILL.md

When it is used

Use when a SQL query is unfamiliar, inherited or suspect and needs a step-by-step explanation with correctness and performance risks pointed out. Do not use for writing a new query from a question or tuning a database server. Related topics: data, education.

What it will ask you for

• Query (longer free text)
• Database (choose one: PostgreSQL, MySQL, SQL Server, BigQuery, SQLite, Snowflake)
• Table descriptions (longer free text)
• Reader's SQL level (choose one: Beginner, Comfortable, Advanced)
• What the result is used for (free text, e.g. "A weekly revenue report")
• Known problem (longer free text)

How it works

1. Summarise in one sentence what the query returns and how the result is used.
2. Walk through the clauses in logical execution order and say which rows each one keeps or removes.
3. Describe every join with its key and flag any that could multiply rows.
4. Check for correctness traps such as fan-out, NULL handling, accidental inner joins and date boundaries.
5. List speed risks and suggest rewrites with check queries that would confirm the totals.

What you get

A one-sentence summary, a clause-by-clause walkthrough pitched at the reader's level, a list of correctness and speed risks, and suggested rewrites with check queries.

What it watches out for

• Explaining the clauses in written order, which hides that WHERE runs before SELECT aliases exist.
• Missing a fan-out from a one-to-many join, which makes totals look plausible but wrong.
• Calling a query slow without table sizes or a plan, when the real cost depends on the data.

How to install

Claude.ai and the Claude desktop app

1. Download the skill .zip.
2. Open Settings, then Capabilities, and find Skills.
3. Choose Upload skill and select the .zip.
4. Ask Claude for help with the task. It loads the skill when your request matches.

Claude Code

1. Download the skill .zip.
2. Unzip it into ~/.claude/skills/ (or .claude/skills/ inside a project).
3. Start a new session. Claude Code loads the skill when your request matches.

Codex

1. Download the skill .zip.
2. Unzip it into ~/.agents/skills/ (or .agents/skills/ inside a project).
3. Codex picks it up on its own. Type $ and the skill name to use it, or just ask for the task.

Cursor

1. Download the Cursor rule (.mdc).
2. Save it in .cursor/rules/ inside your project.
3. Cursor's agent applies the rule when your request matches its description.

AGENTS.md (Codex, Cursor, and other coding agents)

1. Copy the AGENTS.md section.
2. Paste it into AGENTS.md at the root of your repository, creating the file if needed.
3. Coding agents that read AGENTS.md follow it when your request fits.