sql-query-explainer
This skill explains SQL queries in plain English, identifies performance optimizations, and generates new queries from natural language descriptions. Use it when you need to understand existing SQL logic, improve slow queries, translate database syntax for non-technical stakeholders, write queries from business requirements, or create query documentation. It supports PostgreSQL, MySQL, BigQuery, Snowflake, and standard SQL across four modes: explain, optimize, write, and document.
git clone --depth 1 https://github.com/mohitagw15856/pm-claude-skills /tmp/sql-query-explainer && cp -r /tmp/sql-query-explainer/plugins/pm-data/skills/sql-query-explainer ~/.claude/skills/sql-query-explainerSKILL.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. ## Modes Detect which mode the user needs based on their request: 1. **Explain** — Translate existing SQL into plain English 2. **Optimise** — Review SQL for performance issues and suggest improvements 3. **Write** — Generate SQL from a natural language description 4. **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: 1. The SQL query with inline comments 2. 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.] ``` --- ## 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 ## 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?"
Conduct a structured ethical review of an AI or ML feature, model, or product. Use when preparing to deploy an AI system, assessing algorithmic risk, auditing a model for bias, or producing a responsible AI impact assessment. Produces a structured ethics review covering fairness, transparency, privacy, safety, accountability, and societal impact with a risk tier score, pre-deployment checklist, and prioritised mitigations.
Structure AI and ML product decisions with the rigour of any product decision. Use when building AI-powered features, evaluating LLM integrations, designing AI products, or assessing AI readiness. Produces a complete AI product canvas covering problem definition, model approach, data requirements, evaluation framework, UX design, responsible AI checklist, and launch monitoring plan.
Transform feature briefs into structured design briefs that give designers the context they need before opening Figma. Use when asked to write a design brief, create a design handoff, brief a designer on a new feature, or translate a PRD into design requirements. Produces a brief with user goal, emotional context, success criteria, constraints, edge cases, and out-of-scope boundaries.
Design statistically rigorous A/B tests and interpret experiment results. Use when asked to design an experiment, run an A/B test, calculate sample size, interpret test results, or assess whether an experiment was successful. Produces a complete experiment design with hypothesis, sample size, run time, success criteria, and risk flags — or a results interpretation with ship/iterate/kill recommendation.
Synthesises user signals from multiple research sources into a unified, weighted insight brief. Use when you have data from interviews, support tickets, NPS verbatims, app reviews, or sales calls and need to reconcile contradictions, surface the underlying need behind requests, or answer 'what are users really telling us'. Produces ranked insights with confidence ratings, source weighting rationale, divergent signal analysis by user segment, and a research gap identification section.
Structure a product data analysis, metric deep-dive, funnel analysis, or cohort study. Use when asked to analyse product metrics, investigate a drop in conversion, explain a data change to stakeholders, or find the root cause of a metric movement. Produces a structured analysis with question, root cause, confidence level, and recommended action.
Interpret product metrics against goals and surface actionable signals. Use when asked to analyse product health, review key metrics, investigate a performance issue, produce a health report, or assess product-market fit signals. Produces a structured health report with RAG status, trend analysis, root cause hypotheses, and prioritised actions.
Structure a retention analysis, churn investigation, or engagement deep-dive for any product team. Use when asked to analyse user retention, investigate churn, measure DAU/MAU, or build a retention improvement plan. Produces a retention snapshot with root cause hypotheses, aha-moment correlation, and prioritised interventions.