How to use the PostgreSQL Expert agent skill (postgres-expert)

What is an agent skill, and what does this one do?

An agent skill is a folder containing a SKILL.md file of written instructions that an AI agent can load when a task matches it. This skill is not a program: it adds no tools and does not connect to a database by itself. It gives the agent a body of PostgreSQL expertise to apply to your questions.

Once installed, the agent is primed to analyze query plans with EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) before and after changes, choose index types (B-tree, GIN, GiST or BRIN) based on the access pattern, suggest partitioning for time-series tables, and avoid common mistakes such as SELECT * or NOT IN with nullable columns.

• Index guidance: B-tree for equality and range, GIN for full-text and JSONB, GiST for geometric and range types, BRIN for naturally ordered large tables.
• Query guidance: CTE materialization hints, window functions for top-N-per-group, and INSERT ... ON CONFLICT for upserts.
• Partitioning: PARTITION BY RANGE on timestamp columns, combined with partition pruning.
• Operations: VACUUM (VERBOSE) and ANALYZE after bulk loads, pg_stat_statements for slow queries, and pgbouncer in transaction pooling mode for many short-lived connections.

Install the postgres-expert skill

Download the ZIP for this skill from this page. The skill ships as a single file, SKILL.md. You can install it in one of two ways.

For a personal install that applies to all your projects, unzip the download into ~/.claude/skills/. For a single project, unzip it into that project's .claude/skills/ folder instead.

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

• Personal: ~/.claude/skills/postgres-expert/
• Project only: <your-project>/.claude/skills/postgres-expert/

Trigger the skill with natural requests

You do not need a special command. Describe a PostgreSQL task in plain language and mention the database and what you are trying to achieve. The more context you give, such as the query, the table definition and the EXPLAIN output, the more useful the advice.

The skill is most relevant to requests about query optimization, indexing, extensions and database administration.

• "This query on orders takes 8 seconds. Here is the query and its EXPLAIN ANALYZE output. What index should I add?"
• "Design a schema for sensor readings arriving every second. Should I partition the table?"
• "Review this migration for PostgreSQL pitfalls before we run it."
• "Rewrite this NOT IN filter so it handles NULLs correctly."

Work through a typical example

Suppose a reporting query on a large events table is slow. Ask the agent to run or review EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) on the current query, then describe the filter and sort columns. Following the skill's guidance, the agent will look for the right index type and may propose a partial index, such as CREATE INDEX ON orders (created_at) WHERE status = 'pending', or a covering index using INCLUDE (column).

After any change, ask for EXPLAIN ANALYZE again and compare the two plans. The skill's principles call for measuring before and after, so keep both outputs for your review.

What you need before you start

The skill itself needs nothing beyond an agent that supports skills. To get analysis of real queries, you need a PostgreSQL database and access to its query plans, so the agent can work from actual EXPLAIN output rather than guesses.

The skill's advice is only as good as the information you provide. Share table definitions, row counts where relevant, and the query text.

• A PostgreSQL database and access to EXPLAIN output, if you want analysis of real queries.
• Agent access to run commands is up to your setup; the skill itself does not run scripts or use the network.

Safety notes: review before anything touches production

The skill runs no scripts and uses no network access. It is written as instructions and reference guidance only. That is a reason to keep it, but not a guarantee of safe advice: the agent may still propose risky DDL or work_mem settings.

The skill itself warns against setting work_mem globally to a large value, because it is allocated per sort operation and can cause out-of-memory errors under concurrent load. Review every index build, schema change and configuration change yourself, and test on a non-production copy first.

• Do not run agent-suggested DDL on production without review.
• Check any work_mem change, since the skill says to set it per session for analytical work.
• The skill is for PostgreSQL only; advice such as pg_stat_statements or GIN/JSONB does not carry over directly to MySQL or SQL Server.

Tips for better results

Give the agent the full picture in one message. Specific input gets specific output, and the skill's rules, such as avoiding SELECT * and preferring NOT EXISTS, are easier to apply when the query is visible.

Ask the agent to explain its reasoning so you can check it against the plan, and keep transactions short when you review its suggestions, as the skill recommends for lock contention and MVCC bloat.

• Paste the complete query and table definitions, not a summary.
• Ask for the plan before and after each change.
• Ask for a rewrite that uses explicit column lists instead of SELECT *.
• If a partition or index is proposed, ask what write overhead and vacuum work it adds.