SQL Query Optimizer Skill

An evidence-first skill for diagnosing and tuning slow PostgreSQL queries.

This skill pushes the agent to validate the actual bottleneck before recommending rewrites, indexes, settings, or schema changes. It is intentionally workflow-focused: the model already knows PostgreSQL; the skill makes it slow down, ask for the right evidence, and prove the fix worked.

It was distilled from the original SQL Query Optimization Guide.

What It Does

Use this skill when you want an agent to:

• Diagnose a slow Postgres query from SQL and query-plan evidence.
• Review EXPLAIN, EXPLAIN ANALYZE, or EXPLAIN (ANALYZE, BUFFERS) output.
• Decide whether an index is justified.
• Rank query rewrites, statistics fixes, index changes, setting changes, and schema changes.
• Produce a validation plan before calling the optimization done.

The skill is in sql-query-optimizer/.

Install With skills.sh

For Codex, Claude Code, Cursor, and other Agent Skills-compatible tools, use the skills.sh installer:

npx skills@latest add ekeric13/sql-query-optimization-skill

Because this repo contains one skill, the installer should discover sql-query-optimizer directly.

Install For Codex

Install it as a personal Codex skill:

mkdir -p ~/.codex/skills/sql-query-optimizer
rsync -a --delete sql-query-optimizer/ ~/.codex/skills/sql-query-optimizer/

Then start a new Codex session and invoke it explicitly:

Use $sql-query-optimizer to diagnose this slow query.

Codex can also invoke it automatically when the task matches the skill description.

Install For Claude Code As A Plugin

Once this repo is published to GitHub, install it as a Claude Code plugin:

/plugin marketplace add https://github.com/ekeric13/sql-query-optimization-skill

After that finishes, run:

/plugin install sql-query-optimizer@sql-query-optimizer

Or from your shell:

claude plugin marketplace add https://github.com/ekeric13/sql-query-optimization-skill
claude plugin install sql-query-optimizer@sql-query-optimizer

Plugin skills are namespaced. Invoke it as:

/sql-query-optimizer:sql-query-optimizer

This is the best Claude Code install path for sharing the skill with other people because the repo ships .claude-plugin/plugin.json and .claude-plugin/marketplace.json.

Install For Claude Code As A Personal Skill

For local-only use without a plugin marketplace, install it as a personal Claude Code skill:

mkdir -p ~/.claude/skills/sql-query-optimizer
rsync -a --delete sql-query-optimizer/ ~/.claude/skills/sql-query-optimizer/

Then use it in Claude Code:

/sql-query-optimizer

Or ask naturally:

Diagnose this slow Postgres query. Validate the bottleneck before recommending fixes.

Claude Code can load the skill automatically when the request matches the description in SKILL.md.

Install For One Project Only

For Codex project-local use, copy the skill into your repo’s local skills directory if your Codex setup loads project skills from there:

mkdir -p .codex/skills/sql-query-optimizer
rsync -a --delete sql-query-optimizer/ .codex/skills/sql-query-optimizer/

For Claude Code project-local use:

mkdir -p .claude/skills/sql-query-optimizer
rsync -a --delete sql-query-optimizer/ .claude/skills/sql-query-optimizer/

Project-local install is useful when the query-optimization workflow should travel with a repo.

Development Install

If you are editing this skill and want changes to show up without copying after every edit, symlink it:

mkdir -p ~/.codex/skills ~/.claude/skills
ln -sfn "$PWD/sql-query-optimizer" ~/.codex/skills/sql-query-optimizer
ln -sfn "$PWD/sql-query-optimizer" ~/.claude/skills/sql-query-optimizer

For Claude Code, symlinked skills require a recent version that follows symlinks from skill directories.

Verify The Skill

Run the skill validator:

python3 ~/.codex/skills/.system/skill-creator/scripts/quick_validate.py ./sql-query-optimizer

If that system skill path is not present on your machine, run the equivalent validator from your local skill-creator installation.

How To Use It Well

Best input:

• The SQL query.
• EXPLAIN (ANALYZE, BUFFERS) output.
• Existing indexes and table sizes.
• PostgreSQL version.
• Whether this is a read path, write path, dashboard, batch job, or user-facing endpoint.

If you only provide SQL, the skill should label recommendations as low confidence and ask for plan evidence before giving durable fixes.

License

No license has been specified yet. Add one before publishing or distributing this skill.