Sql Query ExplainerCAUTION

1255 professional Agent Skills for Claude, ChatGPT, Gemini, Cursor & Codex — PRDs, postmortems, leases, medical bills, layoffs, go-bags, new countries. Plain markdown, MIT, in Anthropic's plugin directory. Plus a typed decision layer: which skill, is it safe, ship or slip. Free in-browser or npx pm-

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: sql-query-explainer
description: "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."
---

# 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:

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.]
```

---

## Output Format

Every mode returns the same disciplined shape:

1. **The one-line summary** — what this query does, in business language ("monthly revenue per region, excluding refunds"), before any SQL talk.
2. **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).
3. **The gotchas** — NULL behaviour, join fan-out, timezone traps, and index implications that apply to *this* query, not generic advice.
4. **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 quer

CAUTIONgrade B · trust 89/100 Install with care. The audit found things worth knowing before you trust its output.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (5)

templates/pm-discovery-agent/skills/assumption-mapper/SKILL.md

templates/pm-discovery-agent/skills/discovery-interview-guide/SKILL.md

templates/pm-discovery-agent/skills/job-story-mapper/SKILL.md

templates/pm-discovery-agent/skills/user-interview-synthesis/SKILL.md

templates/pm-launch-agent/skills/content-calendar/SKILL.md

Gates applied: no_behavioural_pass.