Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

SQL Query Explainer Skill · mohitagw15856 | DecimalAI

mohitagw15856/sql-query-explainer

SkillScore77Maintained

Explains, optimises, writes, and documents SQL queries. Use when asked to explain a SQL query, optimise slow SQL, translate SQL to plain English for non-technical stakeholders, write a query from a natural language description, or produce query documentation. Produces plain-English explanations, annotated optimised queries, or a data dictionary covering output shape, assumptions, and known limitations. Works across PostgreSQL, MySQL, BigQuery, Snowflake, and standard SQL.

Databy mohitagw15856

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Data Analyst pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/mohitagw15856-sql-query-explainer/SKILL.md

decimalai skills pull mohitagw15856-sql-query-explainer --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/mohitagw15856-sql-query-explainer/SKILL.md https://app.decimal.ai/s/mohitagw15856-sql-query-explainer/SKILL.md

Raw file: /s/mohitagw15856-sql-query-explainer/SKILL.md ↗ · machine-readable summary at /s/mohitagw15856-sql-query-explainer.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 20d ago

Yes — +9% lift · at higher cost+45% tokens0% turns77% of whole cases pass with skill (17/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-01	✗→✓	▲ Improved	34%	0%
case-02	✗→✓	▲ Improved	52%	0%
case-17	✗→✓	▲ Improved	38%	0%
case-22	✗→✓	▲ Improved	46%	0%
case-03	✓→✗	▼ Worse	47%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/10/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

mohitagw15856 / pm-claude-skills

skills/sql-query-explainer/SKILL.md

View on GitHub ↗

License MITImported 8/10/2026Version v1

Skill contents

SKILL.md

SQL Query Explainer Skill

This skill explains SQL queries in plain language, identifies optimisation opportunities, and helps communicate data logic to non-technical stakeholders. It also writes and documents new queries from natural language descriptions.

Required Inputs

The SQL (Explain/Optimise/Document modes) — the actual query, ideally with the dialect named (Postgres, BigQuery, Snowflake, MySQL…); dialect changes both semantics and the optimisation advice.
The intent in plain words (Write mode) — what question the data should answer, plus table/column names if known. Without a schema, assumptions get stated, never silently invented.
Optional but transformative: EXPLAIN/EXPLAIN ANALYZE output and rough table sizes — turns generic advice into advice about your query plan.

Modes

Detect which mode the user needs based on their request:

Explain — Translate existing SQL into plain English
Optimise — Review SQL for performance issues and suggest improvements
Write — Generate SQL from a natural language description
Document — Produce a data dictionary or query documentation

Mode 1: Explain

When given a SQL query, produce:

Plain English Summary

1–3 sentences. What does this query do? What data does it return? Write as if explaining to a business analyst, not a developer.]

Step-by-Step Walkthrough

Break the query into logical sections. For each section:

Quote the SQL clause
Explain what it does in plain English
Flag any complexity (e.g. window functions, subqueries, CTEs)

What the Result Looks Like

Describe the shape of the output: "Returns one row per user, with columns for X, Y, Z. Ordered by field] descending."]

Potential Issues to Flag

Gotchas, edge cases, or implicit assumptions in this query]
e.g. "This will include NULLs in the user_id column if the LEFT JOIN finds no match"]

Mode 2: Optimise

When asked to optimise a query, produce:

Performance Assessment

Rate overall: 🟢 Well-optimised / 🟡 Some improvements possible / 🔴 Significant issues

Issues Found

For each issue:

Issue N]: Short name, e.g. "Missing index on join column"]

What it is: Plain explanation]
Why it matters: Performance impact — e.g. "Full table scan on a 10M row table"]
Fix:

sql
-- Before
[original snippet]

-- After
[improved snippet]

Expected improvement: Estimate if possible]

Optimisation Checklist

] SELECT used? (Replace with specific columns)
] Implicit type conversions on JOIN/WHERE columns?
] Missing indexes on JOIN or WHERE columns?
] N+1 patterns (queries inside loops)?
] DISTINCT used where GROUP BY would be faster?
] Window functions used where a subquery would be clearer/faster?
] CTEs re-used or materialised unnecessarily?
] Large IN() lists that could use a JOIN instead?

Mode 3: Write

When given a natural language description, generate the SQL query and then explain it using Mode 1.

Ask the user to confirm:

Database/dialect (PostgreSQL / MySQL / BigQuery / Snowflake / SQLite / Standard SQL)
Table and column names (if known; otherwise use descriptive placeholder names like users, orders, user_id)
Any filters, sorting, or aggregation requirements

Produce:

The SQL query with inline comments
Plain English explanation (Mode 1 format)

Mode 4: Document

When asked to create documentation for a query or table:

Query Documentation

Query: [Name]
Purpose: [One sentence — what business question this answers]
Author: [If provided]
Last reviewed: [If provided]

Inputs:
  - Table: [table_name] — [what it contains]
  - Filter: [any WHERE conditions and their business meaning]

Output columns:
  | Column | Type | Description |
  |--------|------|-------------|
  | [name] | [type] | [plain English description] |

Assumptions:
  - [Any implicit assumptions the query makes]

Known limitations:
  - [Edge cases not handled, data quality dependencies, etc.]

Output Format

Every mode returns the same disciplined shape:

The one-line summary — what this query does, in business language ("monthly revenue per region, excluding refunds"), before any SQL talk.
The walkthrough or the artifact — mode-dependent: annotated clause-by-clause explanation (Explain), the rewritten query with a diff of what changed and why (Optimise), the new query with stated assumptions (Write), or the doc block (Document).
The gotchas — NULL behaviour, join fan-out, timezone traps, and index implications that apply to this query, not generic advice.
Verification — a small SELECT the user can run to confirm the query does what the summary claims (row counts before/after, a spot-check predicate).

Quality Checks

] Plain English explanation avoids SQL jargon
] Optimisation suggestions include before/after SQL
] Written queries include inline comments
] Output shape is described (columns, row grain, ordering)
] Dialect-specific syntax is flagged when non-standard

Anti-Patterns

Restating the SQL in pseudo-code instead of explaining what it does and returns
Optimisation advice with no before/after query, or no reason the new one is faster
Ignoring the dialect (writing Postgres-only syntax for a MySQL user)
"Looks fine" with no read on correctness, performance, or row grain
Rewriting the query from scratch instead of explaining/optimising the user's

Example Trigger Phrases

"Explain this SQL query: paste query]"
"Optimise this slow query: paste query]"
"Write a SQL query that natural language description]"
"Document this query for my non-technical stakeholders"
"Why is this query returning unexpected results?"

Illustrative Want to see what mohitagw15856/sql-query-explainer would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

9/1/2026, 10:54 UTC · 22 cases

Lift

+9%

77% vs 68%

Agent turns

1.0 vs 1.0

Tokens

+45%

4,144.95 vs 2,854.68

fail → pass · 4pass → pass · 13fail → fail · 3pass → fail · 2

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 Can you analyze this Postgres query to improve its execution speed? SELECT u.id, u.email, COUNT(o.id) as order_count, SUM(o.total_amount) as total_spent FROM users u LEFT JOIN orders o ON u.id = o.user_id WHERE u.created_at >= '2023-01-01' GROUP BY u.id, u.email HAVING COUNT(o.id) > 5; Please give me a high-level summary of what it does, highlight bottleneck issues with side-by-side SQL diffs or code snippets showing how to fix them, list gotchas like null handling, and include a simple validation check query.	fail→pass	25,713	24,726	-4%	1	1	0%	4,025	5,383	+34%	0	0	—
case-02 I need documentation for this BigQuery snippet so our team can maintain it: SELECT c.customer_id, c.region, COALESCE(SUM(s.amount), 0) AS total_revenue, COUNT(DISTINCT s.transaction_id) AS total_orders FROM `company.analytics.customers` c LEFT JOIN `company.analytics.sales` s ON c.customer_id = s.customer_id AND s.sale_date >= '2024-01-01' WHERE c.status = 'ACTIVE' GROUP BY 1, 2; Please create a clean documentation guide detailing its primary objective, input tables and filter conditions, a markdown dictionary of the result fields with data types, known limitations, and a quick verification query.	fail→pass	21,504	21,726	+1%	1	1	0%	2,660	4,053	+52%	0	0	—
case-03 I am designing a PostgreSQL database schema for an e-commerce platform with customers, orders, order line items, and inventory products. Could you write the DDL CREATE TABLE statements with primary keys, foreign key constraints, and cascading deletes?	pass→fail	13,698	20,014	+46%	1	1	0%	2,924	4,306	+47%	0	0	—
case-04 I have two Python Pandas DataFrames, df_customers and df_orders. How do I merge them on customer_id using a left join, group by region, and calculate the mean order value per region in Python?	pass→pass	12,771	13,146	+3%	1	1	0%	1,641	3,883	+137%	0	0	—
case-05 Our executive leadership team wants a visual Tableau dashboard to track quarterly sales KPIs across sales regions. What visual layout, chart choices, and color palette strategy would you recommend for maximum executive clarity?	pass→fail	21,951	20,459	-7%	1	1	0%	2,695	4,101	+52%	0	0	—
case-06 Here is a query running in PostgreSQL: SELECT department_id, employee_id, salary, AVG(salary) OVER (PARTITION BY department_id) as dept_avg_salary, RANK() OVER (PARTITION BY department_id ORDER BY salary DESC) as salary_rank FROM employees WHERE active = true; Explain how this query works, detailing what data it produces, explaining each section, noting gotchas, and providing a check query.	pass→pass	19,697	12,355	-37%	1	1	0%	3,042	3,740	+23%	0	0	—
case-07 Can you break down what this Snowflake SQL query is doing? SELECT user_id, session_id, event_time, event_type FROM user_events WHERE event_time >= '2024-01-01' QUALIFY ROW_NUMBER() OVER (PARTITION BY user_id ORDER BY event_time DESC) = 1; Give me a business summary, step-by-step clause explanation, expected row grain, gotchas, and a validation query.	pass→pass	18,576	10,925	-41%	1	1	0%	2,711	3,675	+36%	0	0	—
case-08 Explain this BigQuery SQL snippet: SELECT o.order_id, o.customer_id, item.product_id, item.price FROM `project.dataset.orders` o, UNNEST(o.line_items) AS item WHERE o.order_date = CURRENT_DATE(); I want a plain language explanation, step-by-step breakdown, output shape, potential edge cases, and a verification snippet.	pass→pass	20,845	19,835	-5%	1	1	0%	2,898	3,582	+24%	0	0	—
case-09 Our MySQL database is running very slowly on this query: SELECT user_id, username, email FROM users WHERE phone_number = 5550199 AND status = 'active'; The phone_number column is indexed and stored as VARCHAR(20). Why is MySQL skipping the index, and how do we fix it? Provide performance rating, before/after code diffs, gotchas, checklist, and test query.	pass→pass	23,029	19,840	-14%	1	1	0%	2,707	3,957	+46%	0	0	—
case-10 Please review this Postgres query for performance bottlenecks and suggest optimizations: SELECT * FROM orders WHERE customer_id IN (SELECT customer_id FROM customers WHERE country = 'CA'); Show before/after SQL fixes, checklist, gotchas, and a verification SELECT.	pass→pass	15,462	18,890	+22%	1	1	0%	2,883	4,019	+39%	0	0	—
case-11 We have this SQLite query that runs slowly on our mobile local database: SELECT DISTINCT customer_id, region FROM sales WHERE sale_year = 2024; Can you evaluate performance, provide optimized SQL with diffs, gotchas, optimization checklist, and verification code?	fail→fail	22,276	19,740	-11%	1	1	0%	3,197	4,166	+30%	0	0	—
case-12 Evaluate this Snowflake query for efficiency improvements: WITH regional_sales AS ( SELECT region, SUM(amount) AS total_amt FROM sales WHERE transaction_date >= '2024-01-01' GROUP BY region ) SELECT * FROM regional_sales WHERE total_amt > 100000; Provide performance assessment, before/after fixes, gotchas, checklist, and verification query.	pass→pass	25,171	19,106	-24%	1	1	0%	2,822	4,033	+43%	0	0	—
case-13 I need a query written for PostgreSQL to find customers who placed an order in Q1 2024 but placed zero orders in Q2 2024. I don't know the exact column names yet. Generate the query with inline comments, business summary, gotchas, and verification query.	fail→fail	22,558	20,297	-10%	1	1	0%	3,141	4,338	+38%	0	0	—
case-14 Generate a BigQuery query that calculates daily active users and 7-day rolling active users for the past month from an analytics events table. Show inline comments, plain English summary, gotchas, and verification check.	fail→fail	17,527	23,802	+36%	1	1	0%	3,058	5,043	+65%	0	0	—
case-15 I need a MySQL query to find the top 3 highest revenue products for each product category in 2024. Write the SQL, explain it in business terms, list gotchas like tie handling, and provide a validation check.	pass→pass	21,912	15,917	-27%	1	1	0%	3,218	4,473	+39%	0	0	—
case-16 Write a Snowflake SQL query to pivot monthly sales figures so that each month (Jan through Dec) appears as its own column for each product_id in year 2024. Provide inline comments, summary, gotchas, and validation query.	pass→pass	24,149	22,027	-9%	1	1	0%	3,053	5,986	+96%	0	0	—
case-17 Produce technical documentation for our monthly recurring revenue (MRR) PostgreSQL reporting query: SELECT DATE_TRUNC('month', subscription_start) AS mrr_month, plan_tier, COUNT(subscription_id) AS active_subs, SUM(monthly_price) AS total_mrr FROM subscriptions WHERE status = 'ACTIVE' AND auto_renew = TRUE GROUP BY 1, 2; Include business summary, inputs, schema dictionary, limitations, and verification query.	fail→pass	14,774	14,686	-1%	1	1	0%	2,806	3,864	+38%	0	0	—
case-18 Please generate documentation for this MySQL query used by our warehouse team: SELECT p.product_id, p.sku, p.stock_quantity, p.reorder_point, s.supplier_name FROM products p JOIN suppliers s ON p.supplier_id = s.supplier_id WHERE p.stock_quantity <= p.reorder_point AND p.is_discontinued = 0; Provide business summary, structured documentation template, edge cases, and verification SELECT.	pass→pass	19,369	18,540	-4%	1	1	0%	2,518	3,460	+37%	0	0	—
case-19 Why is this MySQL query acting like an INNER JOIN and dropping customers without orders? SELECT c.customer_id, c.name, o.order_id, o.order_date FROM customers c LEFT JOIN orders o ON c.customer_id = o.customer_id WHERE o.order_date >= '2024-01-01'; Explain what happens, step-by-step clause analysis, gotchas, and how to verify.	pass→pass	17,549	17,656	+1%	1	1	0%	3,069	3,797	+24%	0	0	—
case-20 Analyze this Postgres query containing correlated subqueries: SELECT u.id, u.name, (SELECT COUNT(*) FROM orders o WHERE o.user_id = u.id) AS order_count, (SELECT MAX(created_at) FROM logs l WHERE l.user_id = u.id) AS last_login FROM users u; Provide performance assessment rating, before/after SQL diff, checklist, gotchas, and validation query.	pass→pass	22,968	23,853	+4%	1	1	0%	3,322	4,648	+40%	0	0	—
case-21 Explain why this PostgreSQL query returns zero rows even though we know there are unmatched records: SELECT * FROM department_employees WHERE employee_id NOT IN (SELECT manager_id FROM departments); Give plain English summary, clause breakdown, gotchas about NULL handling in NOT IN, and a check query.	pass→pass	11,621	10,051	-14%	1	1	0%	2,098	3,298	+57%	0	0	—
case-22 Document this SQLite query for our data catalog: SELECT date(created_at) AS log_date, log_level, COUNT(*) AS entry_count FROM app_logs WHERE created_at >= date('now', '-7 days') GROUP BY 1, 2; Format with summary, input/output documentation, gotchas, and a validation query.	fail→pass	12,308	10,983	-11%	1	1	0%	2,315	3,384	+46%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted. The headline lift of +9 percentage points is the difference between those two pass rates over the 22 comparable cases. 3 cases got worse with the skill loaded, and they are included in that figure.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 68.2%
Pass rate with the skill: 77.3%
Cases attempted: 22
Cases counted toward lift: 22
Cases that regressed: 3
Skill version measured: v1
Run completed: 9/1/2026, 10:54 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-01

Prompt

Can you analyze this Postgres query to improve its execution speed?

SELECT u.id, u.email, COUNT(o.id) as order_count, SUM(o.total_amount) as total_spent
FROM users u
LEFT JOIN orders o ON u.id = o.user_id
WHERE u.created_at >= '2023-01-01'
GROUP BY u.id, u.email
HAVING COUNT(o.id) > 5;

Please give me a high-level summary of what it does, highlight bottleneck issues with side-by-side SQL diffs or code snippets showing how to fix them, list gotchas like null handling, and include a simple validation check query.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run77

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+46% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 20 days ago

Other measured skills in the registry, with their headline benchmark lift.