Agent skill

SQL Insight

by zebbern in zebbern/claude-code-guide

Translate natural language to SQL, optimize query performance, and interpret EXPLAIN plans for SQLite and PostgreSQL.

MITAuto-check passedDatabases

Install SQL Insight

skills CLI
$ npx skills add zebbern/claude-code-guide --skill sql-insight -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install zebbern/claude-code-guide sql-insight --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/zebbern/claude-code-guide.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/sql-insight .claude/skills/sql-insight && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
sql-insight
GitHub stars
4.6k
Token cost
~2.1k tokens
SKILL.md length
530 words
Files
3 (incl. scripts)
Skills in repo
46
Repo updated
First seen
Licence
MIT

At a glance

Translate natural language to SQL, optimize query performance, and interpret EXPLAIN plans for SQLite and PostgreSQL.

  • Works in 4 steps: Use the schema command to extract the… → Use the schema as context to translate… → Use the optimize command to check if the… → …
  • Tasks that involve Query optimization
  • SKILL.md covers Capabilities, Workflow, Quick Start and Detailed Usage, plus 5 more sections
  • Runs Python scripts from its folder; calls python3 and pip

What it does

SQL Insight is an agent skill from zebbern/claude-code-guide. Translate natural language to SQL, optimize query performance, and interpret EXPLAIN plans for SQLite and PostgreSQL. Triggered when users ask to convert questions into SQL, improve slow queries, tune indexes, analyze execution plans, or mention keywords like NL2SQL, query tuning, or full table scan.

Its SKILL.md is about 2.1k tokens, which your agent loads only when the skill is triggered. The skill folder holds 3 other files, including scripts (for example `scripts/sql_query_helper.py`).

It sits in Databases, covering Query optimization and SQL. It works with SQL, SQLite and PostgreSQL. The repository describes itself as: Claude Code Guide - Setup, Commands, workflows, agents, skills & tips-n-tricks from beginner to power user! The licence is MIT.

When your agent uses it

  • Tasks that involve Query optimization
  • Tasks that involve SQL

Example prompts

  • “/sql-insight”

Requirements

  • Python 3

Workflow steps

4 steps, taken from the first numbered list in SKILL.md.

  1. Use the schema command to extract the database table structure
  2. Use the schema as context to translate the user's natural language request into SQL
  3. Use the optimize command to check if the generated SQL can be improved
  4. Use the explain command to verify the query execution plan

What it can do on your machine

Read from SKILL.md and the folder at commit 4698e3b. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Ships 1 file in scripts/ (Python), which the agent can run.

    Shell commands in SKILL.md call:

    • python3
    • pip

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md. Its commands use pip, which can reach the network depending on how they are called.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

SQL Insight loads about 2.1k tokens when it runs. Until then it costs about 78 tokens; SKILL.md has 530 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~78
When it runs · the whole SKILL.md, loaded when a task matches
~2.1k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); the scripts in this folder are not scanned.

SKILL.md

The full file from zebbern/claude-code-guide at commit 4698e3b, republished under its MIT licence (© zebbern). 530 words, ~2,107 tokens.

Download SKILL.mdSave it as .claude/skills/sql-insight/SKILL.md (or your agent's skills folder). This skill also uses 2 other files; get the full folder from GitHub.
name
sql-insight
description
Translate natural language to SQL, optimize query performance, and interpret EXPLAIN plans for SQLite and PostgreSQL. Triggered when users ask to convert questions into SQL, improve slow queries, tune indexes, analyze execution plans, or mention keywords like NL2SQL, query tuning, or full table scan.
license
MIT

sql-insight

SQL query assistant — natural language to SQL translation, query optimization analysis, and EXPLAIN plan interpretation.

Capabilities

FeatureDescription
Schema ExtractionExtracts database table structure (columns, types, indexes, foreign keys, sample data) to provide context for NL→SQL
Natural Language → SQLTranslates natural language descriptions into SQL queries using schema context
Query Optimization AnalysisDetects SQL anti-patterns based on 13 rules and provides optimization suggestions
EXPLAIN InterpretationRuns EXPLAIN and interprets the query plan, identifying full table scans, missing indexes, and more

Workflow

Natural Language → SQL
  1. Use the schema command to extract the database table structure
  2. Use the schema as context to translate the user's natural language request into SQL
  3. Use the optimize command to check if the generated SQL can be improved
  4. Use the explain command to verify the query execution plan
bash
# Step 1: Extract schema (compact mode, suitable for LLM context)
python3 scripts/sql_query_helper.py --db-path data.db schema --compact

# Step 2: Analyze SQL optimization suggestions
python3 scripts/sql_query_helper.py optimize "SELECT * FROM orders WHERE user_id = 100"

# Step 3: View EXPLAIN execution plan
python3 scripts/sql_query_helper.py --db-path data.db explain "SELECT * FROM orders WHERE user_id = 100"

Quick Start

Schema Extraction
bash
# Extract full schema (JSON format, with sample data)
python3 scripts/sql_query_helper.py --db-path data.db schema

# Compact mode (plain text, suitable for embedding in prompts)
python3 scripts/sql_query_helper.py --db-path data.db schema --compact

# Skip data sampling
python3 scripts/sql_query_helper.py --db-path data.db schema --sample-rows 0

# PostgreSQL
python3 scripts/sql_query_helper.py --db-type postgres --dsn "host=localhost dbname=mydb user=reader" schema --compact
Query Optimization Analysis
bash
# Analyze SQL query (no database connection required, pure rule-based detection)
python3 scripts/sql_query_helper.py optimize "SELECT * FROM orders o, users u WHERE o.user_id = u.id"

python3 scripts/sql_query_helper.py optimize "SELECT name FROM users WHERE UPPER(email) LIKE '%@GMAIL.COM'"

python3 scripts/sql_query_helper.py optimize "SELECT id, (SELECT COUNT(*) FROM orders WHERE user_id = u.id) AS order_count FROM users u"
EXPLAIN Interpretation
bash
# SQLite EXPLAIN
python3 scripts/sql_query_helper.py --db-path data.db explain "SELECT * FROM orders WHERE user_id = 100"

# PostgreSQL EXPLAIN
python3 scripts/sql_query_helper.py --db-type postgres --dsn "host=localhost dbname=mydb" explain "SELECT * FROM orders WHERE user_id = 100"

# PostgreSQL EXPLAIN ANALYZE (actually executes the query for real-world data)
python3 scripts/sql_query_helper.py --db-type postgres --dsn "host=localhost dbname=mydb" explain --analyze "SELECT * FROM orders WHERE user_id = 100"

Detailed Usage

Global Parameters
ParameterRequiredDefaultDescription
--db-typeNosqliteDatabase type: sqlite or postgres
--db-pathFor schema/explain (SQLite)—SQLite database file path
--dsnFor schema/explain (PostgreSQL)—PostgreSQL connection string
Subcommands
CommandRequires DatabaseDescription
schemaYesExtract database table structure
optimize <sql>NoSQL query optimization analysis (pure rule-based detection)
explain <sql>YesRun EXPLAIN and interpret the plan
schema Parameters
ParameterDefaultDescription
--sample-rows, -n3Number of sample rows per table (0 to skip sampling)
--compactfalseCompact text output (suitable for embedding in prompts)
explain Parameters
ParameterDefaultDescription
--analyzefalseUse EXPLAIN ANALYZE (PostgreSQL only; actually executes the query)

Optimization Rules

The optimize command detects the following 13 SQL anti-patterns:

RuleSeverityDescription
avoid-select-starwarningAvoid SELECT *; explicitly list column names
unbounded-queryinfoMissing WHERE and LIMIT clauses
leading-wildcard-likewarningLIKE '%...' causes index to be bypassed
or-conditioninfoOR conditions may prevent index usage
not-in-subquerywarningNOT IN (subquery) has poor performance
scalar-subquerywarningScalar subqueries in SELECT execute row-by-row
function-on-columnwarningFunctions on columns in WHERE prevent index usage
implicit-joininfoImplicit joins (comma-separated tables) are less readable
distinct-usageinfoDISTINCT may mask JOIN duplication issues
order-without-limitinfoORDER BY without LIMIT
deep-nestingwarningDeeply nested subqueries
having-without-groupwarningHAVING without GROUP BY
not-equal-filterinfo!= conditions cannot effectively use indexes
Show full SKILL.md (168 more words)Show less

EXPLAIN Interpretation Items

CheckApplicable DatabaseDescription
Full table scanSQLite / PostgreSQLDetects Seq Scan / SCAN TABLE
Auto temporary indexSQLiteSQLite auto-creates a temporary index, indicating a missing permanent index
Covering indexSQLite / PostgreSQLIndex contains all queried columns; no table lookup needed
Disk sortPostgreSQLSort operation spills to disk
Nested loop joinPostgreSQLNested loop joins on large tables have poor performance
Row estimate deviationPostgreSQL (ANALYZE)Estimated rows differ from actual rows by more than 10x

Output Examples

schema --compact
-- Database: sqlite
-- users (1500 rows): id INTEGER  PK, name TEXT, email TEXT, age INTEGER, created_at TEXT
--   IDX(unique): idx_users_email on (email)
-- orders (8200 rows): id INTEGER  PK, user_id INTEGER, amount REAL, status TEXT, created_at TEXT
--   FK: user_id -> users.id
--   IDX: idx_orders_user_id on (user_id)
optimize
json
{
  "sql": "SELECT * FROM orders o, users u WHERE o.user_id = u.id",
  "issues": [
    {
      "severity": "warning",
      "rule": "avoid-select-star",
      "message": "Avoid SELECT *: only select the columns you need to reduce I/O and network transfer",
      "suggestion": "Replace SELECT * with an explicit list of required column names"
    },
    {
      "severity": "info",
      "rule": "implicit-join",
      "message": "Uses implicit join (comma-separated tables), which is less readable and error-prone",
      "suggestion": "Use explicit JOIN ... ON syntax for better readability and maintainability"
    }
  ]
}
explain (SQLite)
json
{
  "db_type": "sqlite",
  "query": "SELECT * FROM orders WHERE user_id = 100",
  "plan": [
    {"id": 2, "parent": 0, "detail": "SEARCH orders USING INDEX idx_orders_user_id (user_id=?)"}
  ],
  "interpretation": [
    {
      "severity": "ok",
      "type": "index-search",
      "detail": "Index lookup: idx_orders_user_id",
      "suggestion": "Index lookup is efficient"
    }
  ]
}

Safety Mechanisms

  • Read-only connections: SQLite uses ?mode=ro; PostgreSQL uses SET SESSION READ ONLY
  • SQL whitelist: Only allows statements starting with SELECT / WITH / EXPLAIN
  • Dangerous keyword blocking: INSERT, UPDATE, DELETE, DROP, and 30+ other keywords are blocked
  • Multi-statement blocking: Semicolon-separated multiple SQL statements are rejected
  • Identifier escaping: Table names are double-quote escaped to prevent SQL injection

Dependencies

  • Python 3.8+ (sqlite3 is a built-in module)
  • PostgreSQL support requires: pip install psycopg2-binary
  • The optimize command requires no database connection and has zero external dependencies

© zebbern, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 2 other files (scripts) in skills/sql-insight of zebbern/claude-code-guide.

  • SKILL.md
  • LICENSE
  • scripts/sql_query_helper.py

Open the folder on GitHubat commit 4698e3b

Compare with similar skills

SQL Insight next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

SQL Insight compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
SQL Insight this skillzebbern/claude-code-guide4.6k—~2.1kAutomated safety check: PassMIT
SQL Expertaiskillstore/marketplace430—~3.4kAutomated safety check: PassNone
SQL ToolkitLeoYeAI/openclaw-master-skills2.2k—~3kAutomated safety check: PassMIT
SQL Database Support for pRESTprest/prest4.6k—~1.6kAutomated safety check: PassMIT
PostgreSQL Documentation Reference2025Emma/vibe-coding-cn23k1 repos~19kAutomated safety check: PassMIT
Squixeduardofuncao/squix273—~784Automated safety check: PassMIT

Similar skills

  • SQL Expert

    aiskillstore/marketplace

    Expert SQL query writing, optimization, and database schema design with support for PostgreSQL, MySQL, SQLite, and SQL Server.

    430 GitHub stars~3.4k tokensUpdated today
    DatabasesAuto-check passed
  • SQL Toolkit

    LeoYeAI/openclaw-master-skills

    Query, design, migrate, and optimize SQL databases. An agent skill from LeoYeAI/openclaw-master-skills.

    2.2k GitHub stars~3k tokensUpdated 2 mo ago
    DatabasesAuto-check passed
  • Guides classifying, gap-analyzing and scaffolding support for a new SQL database in pREST, from Postgres-compatible variants to entirely new dialects.

    4.6k GitHub stars~1.6k tokensUpdated yesterday
    DatabasesAuto-check passed
  • PostgreSQL Documentation Reference

    2025Emma/vibe-coding-cn

    PostgreSQL database documentation - SQL queries, database design, administration, performance tuning, and advanced features. Use when working with PostgreSQL…

    23k GitHub starsUsed in 1 repo~19k tokens
    DatabasesAuto-check passed
  • Squix

    eduardofuncao/squix

    Run SQL queries across databases (Postgres, MySQL, SQLite, etc.) via the squix CLI.

    273 GitHub stars~784 tokensUpdated 14 days ago
    DatabasesAuto-check passed
  • Comprehensive guide for Go database access — parameterized queries, struct scanning, NULLable columns, transactions, isolation levels, SELECT FOR UPDATE, connection pool, batch processing, context…

    240 GitHub starsUsed in 2 repos~2.9k tokens
    DatabasesAuto-check passed

More from zebbern/claude-code-guide

All 46 skills in this repo
  • Localization Toolkit

    zebbern/claude-code-guide

    This skill should be used when setting up, auditing, or enforcing internationalization/localization in UI codebases (React/TS, i18next or similar, JSON locales), including installing/configuring the…

    4.6k GitHub starsUsed in 1 repo~1.3k tokens
    Auto-check passed
  • Audit Flow

    zebbern/claude-code-guide

    Interactive system flow tracing across CODE, API, AUTH, DATA, NETWORK layers with SQLite persistence and Mermaid export.

    4.6k GitHub stars~4.2k tokensUpdated today
    Auto-check passed
  • Chart Image

    zebbern/claude-code-guide

    Generate publication-quality PNG chart images from data, supporting line, bar, area, candlestick, pie, and heatmap charts.

    4.6k GitHub stars~2.7k tokensUpdated today
    Auto-check passed
  • Code To Diagram

    zebbern/claude-code-guide

    Analyze codebases and automatically generate architecture diagrams, flowcharts, and org charts.

    4.6k GitHub stars~972 tokensUpdated today
    Auto-check passed
  • Code Vuln Audit

    zebbern/claude-code-guide

    Scan code for security issues: dependency vulnerabilities (npm/pip audit), secret leaks (regex and entropy analysis), and OWASP anti-patterns like SQL injection, XSS, or command injection.

    4.6k GitHub stars~1.3k tokensUpdated today
    Auto-check passed
  • Data Viz Renderer

    zebbern/claude-code-guide

    Generate self-contained HTML/SVG infographics from JSON data, including stat cards, bar charts, flow diagrams, and mixed dashboards.

    4.6k GitHub stars~1.3k tokensUpdated today
    Auto-check passed

Categories

Questions about SQL Insight

What does SQL Insight do?

Translate natural language to SQL, optimize query performance, and interpret EXPLAIN plans for SQLite and PostgreSQL. SQL Insight is an agent skill from zebbern/claude-code-guide. Translate natural language to SQL, optimize query performance, and interpret EXPLAIN plans for SQLite and PostgreSQL.

When should I use SQL Insight?

SQL Insight fits situations like: tasks that involve Query optimization; tasks that involve SQL.

How do I install SQL Insight in Claude Code?

Run `npx skills add zebbern/claude-code-guide --skill sql-insight -a claude-code`. Or copy the skill folder (skills/sql-insight in zebbern/claude-code-guide) into .claude/skills/sql-insight in your project. Claude Code loads it when a task matches its description.

How do I install SQL Insight in Codex?

Run `npx skills add zebbern/claude-code-guide --skill sql-insight -a codex`. Or copy the skill folder (skills/sql-insight in zebbern/claude-code-guide) into .agents/skills/sql-insight in your project. Codex loads it when a task matches its description.

Can I use SQL Insight in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add zebbern/claude-code-guide --skill sql-insight -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/sql-insight, .gemini/skills/sql-insight, .github/skills/sql-insight and .opencode/skills/sql-insight in your project.

What does SQL Insight need to run?

Going by SKILL.md and its folder, SQL Insight needs Python for the scripts in its folder and the command-line tools its instructions call (python3 and pip). Our summary lists: Python 3.

Does SQL Insight access the network?

SKILL.md contains no URLs. Its commands use pip, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is SQL Insight safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. The check reads SKILL.md only: the scripts in the folder are not scanned, so read them before running anything.

What licence does SQL Insight use?

SQL Insight is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does SQL Insight use?

About 2.1k tokens (SKILL.md is roughly 8.4k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to SQL Insight?

Skills that share tags, products or a category with SQL Insight: SQL Expert (aiskillstore/marketplace, 430 stars), SQL Toolkit (LeoYeAI/openclaw-master-skills, 2.2k stars), SQL Database Support for pREST (prest/prest, 4.6k stars) and PostgreSQL Documentation Reference (2025Emma/vibe-coding-cn, 23k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains SQL Insight?

zebbern (a GitHub user) maintains it in zebbern/claude-code-guide, which has 4,648 GitHub stars. The repository holds 46 skills in this directory. The repository was last updated on October 7, 2026.

Source: zebbern/claude-code-guide on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.