Guide · Agent skill
How to use the SQL Query Analyst agent skill (sql-analyst)
Updated · written with AI from the project's own documentation and checked against our catalogue data
The SQL Query Analyst skill (sql-analyst) is a set of written guidelines that makes an AI agent answer SQL questions like a database expert. It is useful for developers writing or tuning queries, analysts learning window functions and null handling, and teams designing a new schema. After this guide you will know what the skill changes, how to install it, how to trigger it, and where its limits are.
SQL Query AnalystRightNow-AI/openfang · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Download the sql-analyst ZIP from this page. It contains SKILL.md.
- 2Unzip into a skills folder. Unzip into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the ZIP.
- 4Name your database engine. State whether you use PostgreSQL, MySQL, SQLite or SQL Server in your request.
- 5Ask a natural SQL question. Describe the query, schema or analysis task in plain language, with table definitions if you have them.
- 6Measure suggested changes. Compare EXPLAIN or EXPLAIN ANALYZE output on a copy of your data before applying any index or rewrite.
What is an agent skill and what does sql-analyst change?
An agent skill is a folder containing a SKILL.md file of instructions that an AI agent loads when a task matches it. The sql-analyst skill tells the agent to act as a SQL expert covering query writing, optimization, schema design and data analysis across PostgreSQL, MySQL, SQLite, SQL Server and other SQL dialects.
With the skill active, the agent first asks which dialect you use, writes readable SQL with consistent casing and aliases, and suggests performance fixes such as indexes, EXPLAIN plans, keyset pagination and avoiding functions on indexed columns.
- Dialect-aware answers: it asks which SQL dialect you use before giving syntax.
- Query advice: explicit JOIN syntax, EXISTS instead of IN for existence checks, no SELECT * in production queries.
- Schema guidance: normalization to at least 3NF for transactional work, data types, NOT NULL, foreign keys with explicit ON DELETE, created_at and updated_at columns.
- Analysis patterns: window functions, GROUP BY with HAVING, COALESCE and NULLIF.
Install the sql-analyst skill
Download the sql-analyst ZIP from this page and unzip it. The package contains a single file, SKILL.md. Then choose one of the install locations below.
For a personal install that applies to all your projects, unzip into your user skills folder ~/.claude/skills/. For a single project, unzip into that project's .claude/skills/ folder.
In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/sql-analyst/SKILL.md
- Project only: .claude/skills/sql-analyst/SKILL.md inside your project
Trigger the skill with natural requests
You do not need a special command. Ask a SQL question in plain language that matches the skill's purpose: optimizing a query, designing a table, or analysing data. The agent will apply the skill's guidelines to the answer.
Mention your database engine in the request. The skill asks for it anyway, and naming it up front avoids a round trip.
- Optimize this PostgreSQL query that filters orders by year and is slow.
- Design a schema for a multi-tenant invoicing app in MySQL with proper foreign keys.
- Give me a running total of sales per region using window functions in SQLite.
- Why does my GROUP BY query return NULL totals and how do I handle nulls?
- Should I add an index on this JOIN column, and how do I check with EXPLAIN ANALYZE?
Examples of what the agent will suggest
A common case is a date filter wrapped in a function. The skill advises against WHERE YEAR(created_at) = 2025 because it prevents index use, and recommends a range condition on created_at instead.
Deep pagination is another. The skill says not to use OFFSET for deep pages and to use keyset pagination such as WHERE id > last_seen_id.
-- Instead of filtering with a function on the indexed column:
-- WHERE YEAR(created_at) = 2025
-- use a range condition:
-- WHERE created_at >= '2025-01-01' AND created_at < '2026-01-01'What the skill needs and how it stays safe
The skill lists no requirements. It does not run scripts and does not use the network. It is only written guidelines, and it cannot connect to any database, so it will never run queries against your data.
Its advice should still be checked. The skill itself warns not to add indexes without measuring, because too many indexes slow writes and increase storage. Test suggested changes on a copy or staging database and compare EXPLAIN output before applying them to production.
- Requires: nothing listed.
- Runs scripts: no. Uses network: no.
- Files: SKILL.md only.
- Always use parameterized queries when user input reaches SQL, as the skill advises.
Tips for getting better answers
Give the agent the schema, the exact query and the dialect. The skill's advice depends on the details, and concrete table definitions let it reason about indexes, types and joins.
Ask for the plan, not just the rewrite. The skill favours EXPLAIN or EXPLAIN ANALYZE, so request the plan before and after a change to confirm it helped.
- Paste CREATE TABLE statements alongside the query.
- State your row counts roughly, since they affect whether an index is worth it.
- Ask about null handling explicitly when totals look wrong.
What people use it for
- Rewriting a slow reporting query to use range conditions and proper joins.
- Designing a normalized schema with foreign keys and explicit ON DELETE behaviour.
- Calculating running totals, rankings and period-over-period comparisons with window functions.
- Learning GROUP BY, HAVING and null handling with COALESCE and NULLIF.
Frequently asked questions
How do I install the sql-analyst skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.
Does sql-analyst require any other software or accounts?
The skill lists no requirements. It is a single SKILL.md file of guidelines, runs no scripts and uses no network.
Can the sql-analyst skill run queries on my database?
No. The skill cannot connect to any database. It gives advice, and you run and test any queries yourself.
Which databases does sql-analyst support?
The skill is written for PostgreSQL, MySQL, SQLite, SQL Server and other SQL dialects. It asks which dialect you use because syntax differs between them. It does not cover non-SQL stores such as document or graph databases.
Is sql-analyst safe to use with production databases?
Its advice is not tied to any connection, so it cannot touch production data itself. However, the skill warns against adding indexes without measuring, so test any suggested index or rewrite on a copy before applying it to production.
How is this different from just asking a chatbot SQL questions?
The skill loads a fixed set of rules into the agent, such as asking for your dialect, avoiding SELECT *, using keyset pagination and parameterized queries. Those rules shape every answer consistently, instead of depending on each conversation's prompt.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use sql-analyst if you write or tune SQL, learn analysis patterns, or design a new schema and want consistent, safety-minded guidance from an AI agent. Pick something else if you need the agent to run queries against a live database, or if your data lives in a document or graph store, since this skill covers neither.
Download the skill