Skip to content
Get packs

Guide · Agent skill

How to use the SQL Pro agent skill: query tuning and schema help

Updated · written with AI from the project's own documentation and checked against our catalogue data

SQL Pro is an agent skill from the Jeffallan/claude-skills collection that gives an AI agent a set of SQL guidelines and reference notes for query optimization, complex query writing and database schema design. It is aimed at developers debugging slow queries, analysts writing multi-step reports, and engineers porting queries between database engines. After this guide you will know what the skill changes about the agent's answers, how to install it, how to ask for help in plain language, and what to check before you trust its SQL.

SQL ProJeffallan/claude-skills · MIT

Quick start

  1. 1Download the ZIP. Get the sql-pro skill ZIP from the directory page.
  2. 2Unzip into a skills folder. Place the sql-pro folder in ~/.claude/skills/ for personal use, or .claude/skills/ inside a project.
  3. 3Or upload in the Claude apps. Go to Settings → Capabilities → Skills and upload the skill.
  4. 4Describe your problem. Ask in plain language, such as why a query is slow or how to write a window function query.
  5. 5Provide your query and plan. Paste the SQL, the schema and the EXPLAIN ANALYZE output, and name your database engine.
  6. 6Review and test the output. Check every suggested statement and index, then measure before and after on your own data.

What is an agent skill, and what does SQL Pro make the agent do?

An agent skill is a folder of instructions and reference notes that an AI agent loads when a request matches the skill's description. The skill shapes how the agent answers; it does not add new tools to the agent.

SQL Pro covers three kinds of work: optimizing queries that are slow, writing complex queries (joins, aggregations, CTEs, window functions, recursive queries), and designing or migrating schemas. It steers the agent toward reading execution plans with EXPLAIN ANALYZE, suggesting covering indexes, and writing set-based queries instead of row-by-row logic. It also includes notes on how PostgreSQL, MySQL, SQL Server and Oracle differ.

  • Reads and interprets EXPLAIN / EXPLAIN ANALYZE output
  • Suggests indexing strategies, including covering indexes
  • Writes CTEs, window functions and recursive queries
  • Explains dialect differences when porting SQL between PostgreSQL, MySQL, SQL Server and Oracle
  • The skill itself runs no code; it shapes the agent's advice and SQL output

Install the sql-pro skill from the ZIP

Download the sql-pro ZIP from the directory page. Unzip it so the skill folder (containing SKILL.md and the references folder) sits in one of the locations below.

For a personal install across all your projects, unzip into ~/.claude/skills/. For a single project, unzip into that project's .claude/skills/ folder so it applies only there.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

  • Personal: ~/.claude/skills/sql-pro/
  • Project only: .claude/skills/sql-pro/ inside your project folder
  • Claude apps: Settings → Capabilities → Skills, then upload
~/.claude/skills/sql-pro/SKILL.md

Trigger the skill with natural requests

You do not need a special command. The skill's description lists the situations it covers, so ask in plain language about the problem you have. Mention your database engine if you know it, because the advice differs by dialect.

Good requests include the query itself, the table sizes if you know them, and what you already tried. Pasting the EXPLAIN ANALYZE output gives the agent the most to work with.

  • "Why is this PostgreSQL query slow? Here is the EXPLAIN ANALYZE output."
  • "Write a query that returns each customer's latest completed order using a window function."
  • "Convert this SQL Server query to MySQL and point out the differences."
  • "Suggest a covering index for this query that filters on created_at and sums amount."
  • "Review my schema for orders and order_items and tell me where it breaks normalization."

Examples of what the skill produces

The skill's reference examples show the pattern it favours. A common case is replacing a correlated subquery that runs once per row with a single aggregation join, backed by a covering index that includes the columns the query reads.

The skill also teaches the agent what to look for in plan output. For PostgreSQL, a Seq Scan on a large table suggests adding or fixing an index. When actual row counts are far from estimates, the notes suggest running ANALYZE on the table to refresh statistics. High shared read counts in the buffers output point to disk I/O rather than cache hits.

CREATE INDEX idx_order_items_order_qty ON order_items (order_id) INCLUDE (quantity);

What you need before you start

The skill lists no required tools, no scripts and no network access. It is text guidance that the agent reads, so the practical requirement is an agent environment that supports skills and a copy of your query, schema or plan output to paste in.

The skill cannot see your database. Anything it says about performance is a hypothesis until you measure it on your own data.

  • No listed requirements
  • Runs scripts: no
  • Uses network: no
  • You need access to your own database to run EXPLAIN ANALYZE and verify changes

Safety notes: review before running anything

The skill advises on SQL but does not test it. Review every generated statement before running it, especially anything that writes, alters or drops data.

EXPLAIN ANALYZE actually executes the query. On large tables this can be costly, so consider running it on a copy or a non-peak window. The skill's own workflow asks for verification on production-scale data volumes, but that testing is your responsibility.

  • Do not run generated DDL or DML against production without review
  • Run EXPLAIN ANALYZE with care on large tables, since it executes the query
  • Treat the sub-100ms target in the skill as a goal to verify, not a guaranteed result
  • The skill is for relational SQL; it does not apply to document or key-value stores

Tips for getting better results

Give the agent the exact engine and version family you use, because syntax and plan output differ. Ask for the reasoning behind each index so you can judge it. Compare before and after timings yourself.

The skill's own rules discourage SELECT * in production queries and cursors where set-based work will do, so expect the agent to flag those patterns.

  • Always state the database engine (PostgreSQL, MySQL, SQL Server or Oracle)
  • Paste the full EXPLAIN ANALYZE output, not a summary
  • Ask for before and after versions of the query with the index rationale
  • Measure results on your own data volumes

What people use it for

  • Diagnosing a slow PostgreSQL or MySQL query by reading its execution plan and suggesting indexes
  • Writing a multi-step report with CTEs and window functions, such as latest order per customer
  • Converting a SQL Server query into an equivalent for MySQL, PostgreSQL or Oracle
  • Reviewing a schema for normalization problems such as non-atomic columns or partial dependencies
  • Replacing a correlated subquery with a set-based aggregation join

Frequently asked questions

How do I install the sql-pro skill?

Download the sql-pro ZIP, then unzip it into ~/.claude/skills/ for personal use or into a project's .claude/skills/ folder for one project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.

Is the sql-pro skill free to use?

The skill is published under the MIT licence, as stated on its page. Check the licence file in the source repository for the full terms.

Does sql-pro need any other tools or software installed?

The skill lists no required tools, runs no scripts and uses no network access. You still need your own database to run EXPLAIN ANALYZE and test any changes.

Which databases does sql-pro cover?

It covers PostgreSQL, MySQL, SQL Server and Oracle, including differences such as auto-increment syntax and string concatenation. It is not meant for non-SQL databases like document or key-value stores.

Will sql-pro guarantee my query runs fast?

No. The skill cannot see your data or database. Its performance targets, including the sub-100ms goal, must be verified against your own data.

Is it safe to run the SQL the skill writes?

Review it first. The skill advises on SQL but does not test it, and EXPLAIN ANALYZE executes the query, which can be costly on large tables. Do not run unreviewed changes against production.

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 Pro if you are a developer or analyst who wants a structured approach to reading query plans, writing complex SQL, or porting queries between PostgreSQL, MySQL, SQL Server and Oracle. Pick something else if you work with non-SQL databases or need a tool that tests queries against your database for you, since this skill only shapes the agent's advice.

Download the skill