A Claude Code skill that turns unfamiliar SQL into an interactive, visual HTML explainer.
Paste a query, DML statement, stored procedure, or multi-statement script — get back a shareable artifact
with CTE flow, lineage, write targets, business meaning, and risk flags.

---

Who is this for?

Data engineers who read and review SQL every day, but still run into inherited production queries that are painful to reason about.

You've got a 150-line query, an INSERT ... SELECT, a MERGE, or a stored procedure with audit logging and control flow. It works, or at least it used to. But understanding it means tracing aliases, hopping between CTEs, and mentally reconstructing what data moves where.

This skill generates an explainer that helps you answer the questions that actually matter:

• What does each step produce?
• Where does the data come from?
• What gets written, and when?
• Which parts are real data flow versus run-control bookkeeping?
• Where could the logic silently go wrong?

Your goals are practical, not academic:

• Understand inherited SQL faster
• Review production logic without tracing it manually
• Catch join, null, and write risks earlier
• Debug data pipelines without reading everything top to bottom
• Explain a query or procedure to teammates in one shareable artifact

You're not looking for SQL tutorials, EXPLAIN plans, dbt lineage, or ER diagrams — this is a logic explainer for people who already know SQL.

What the explainer looks like

The output is a single HTML file: portable, shareable, zero dependencies for the viewer. By default it loads fonts and graph libraries from CDNs; ask for offline mode if you need a fully self-contained file.

Interactive DAG

Color-coded nodes for source tables, CTEs, subqueries, final outputs, and write targets — laid out as a dependency graph you can pan, zoom, and click.

Click-to-expand side panel

Click any node to open a detail panel with What, Why, Key Points, risk flags, and the exact syntax-highlighted SQL — unmodified from the original.

Dual-lane view for procedures

Stored procedures mix real transformations with audit inserts, row counts, and control flow. The explainer separates the main data path from ops/bookkeeping so neither fragments the other.

Rich annotations with risk flags

Every node gets a What/Why/Key Points breakdown. Risk flags — fan-out joins, NULL propagation, broad writes, missing idempotency guards — are first-class, not an afterthought.

How to use

Install as a Claude Code skill

1. Copy these files into ~/.claude/skills/sql-explainer/:

   SKILL.md
   sql-analyzer.md
   scripts/
   assets/
   

   You don't need test-sqls/, tests/, examples/, or docs/ — those are for development and this README.
2. Open any project in Claude Code
3. Give it SQL inline or point it at a .sql file

Example prompts:

• "Explain this SQL visually"
• "Turn this query into an HTML explainer"
• "Map the lineage and risks in this SQL file"
• "Visualize this stored procedure"
• "Show me the data flow in this script"

If the SQL is a very simple read-only SELECT, the skill may answer with a concise text explanation unless you explicitly ask for the HTML artifact.

What you can give it

• A pasted query
• A .sql file path
• DML like INSERT, MERGE, UPDATE, DELETE, or CREATE TABLE AS
• Stored procedures and multi-statement scripts
• Optional DDL alongside the SQL for richer column context
• An optional dialect hint such as postgres, bigquery, snowflake, or duckdb

No database connection is required.

Design philosophy

Show structure before detail

The graph gives you the shape of the SQL first. The side panel gives you the exact SQL and the interpretation second. You should not need to read 200 lines just to understand the pipeline.

Explain logic, not syntax

This skill assumes strong SQL fluency. The value is in explaining dependencies, business intent, write behavior, and gotchas — not in teaching what a GROUP BY is.

Risk flags are first-class

The most useful question is often not "What does this do?" but "Where can this quietly go wrong?" Risk flags are part of the main output, not an afterthought.

Separate data flow from bookkeeping

Stored procedures often mix real transformations with audit inserts, row counts, guards, and branch logic. Those control-path nodes matter, but they should not fragment the main data story by default.

Never rewrite the SQL

The explainer annotates the real SQL. It does not replace it with toy examples or simplified pseudo-code.

How it works

Input SQL (paste or file path)
        │
        ▼
┌─────────────────────────┐
│  Phase 1: Analyze       │  Subagent parses CTEs, source tables, write targets,
│  (sql-analyzer.md)      │  control flow; annotates each node with What/Why/
│                         │  Key Points, column lineage, and risk flags
└───────────┬─────────────┘
            │ structured JSON
            ▼
┌─────────────────────────┐
│  Phase 2: Render        │  Deterministic Python renderer builds a single HTML
│  (render_sql_explainer) │  file with Cytoscape.js DAG, side panel, and styling
└───────────┬─────────────┘
            │
            ▼
   sql_explain_<timestamp>.html → auto-opens in browser

Repo structure

sql-explainer/
│
│  Core skill (copy these to ~/.claude/skills/sql-explainer/)
├── SKILL.md                          # Main skill instructions and orchestration
├── sql-analyzer.md                   # SQL analysis subagent prompt and JSON contract
├── scripts/
│   └── render_sql_explainer.py       # Deterministic HTML renderer
├── assets/
│   ├── sql_explainer_template.html   # Single-file HTML shell
│   ├── sql_explainer.css             # Renderer-owned styles
│   └── sql_explainer.js              # Renderer-owned interactivity
│
│  Development and examples (not needed to run the skill)
├── examples/                         # Pre-built HTML explainers for every test case
├── test-sqls/                        # Sample SQL inputs for validation
├── tests/                            # Renderer unit tests and fixtures
└── docs/                             # Screenshots and logo for this README

---

Built by Trish X with Claude Code, Codex and Gemini.