How to use the PostgreSQL Patterns agent skill

What is an agent skill, and what does postgres-patterns do?

An agent skill is a folder containing a SKILL.md file with instructions that an AI agent can load when a task matches the skill's description. This one is named postgres-patterns and is based on Supabase best practices, with the original work credited to the Supabase team under the MIT License.

When the skill is active, the agent answers and writes PostgreSQL code using the skill's quick reference. It suggests index types such as B-tree, GIN and BRIN, and better column types such as bigint IDs, timestamptz timestamps and numeric(10,2) for money. It also offers efficient cursor pagination, upserts with ON CONFLICT, Row Level Security policies, and ready-made SQL for finding unindexed foreign keys, slow queries and table bloat.

How do you install the postgres-patterns skill?

Download the skill's ZIP file from this page. Then choose one of two routes.

For a personal install, unzip the file into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder instead. Either way, the postgres-patterns folder should contain the SKILL.md file.

You can also upload the skill in the Claude apps by going to Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Project only: unzip into .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload

How do you trigger the skill with natural requests?

You usually do not need a special command. The skill's description covers PostgreSQL query optimization, schema design, indexing and security, so ask for those things in plain language and the agent can load it. The skill itself lists these situations as cases to activate on: writing SQL queries or migrations, designing schemas, troubleshooting slow queries, implementing Row Level Security, and setting up connection pooling.

Name the database engine and the goal. Mentioning PostgreSQL, the table and the problem gives the agent enough context to pick the right patterns.

• Which index should I add for a WHERE status = 'pending' AND created_at > ... query in PostgreSQL?
• Review this migration for PostgreSQL data type problems, such as money stored as float.
• Write cursor pagination for my products table in PostgreSQL instead of OFFSET.
• Find unindexed foreign keys in my Postgres database.
• Write an RLS policy so users only see their own orders in Supabase.

What kinds of examples does the skill produce?

The skill's reference includes a composite index that puts equality columns before range columns, a covering index using INCLUDE, a partial index filtered on deleted_at IS NULL, and an optimized RLS policy that wraps auth.uid() in a SELECT. It also includes an UPSERT, a queue-processing pattern using FOR UPDATE SKIP LOCKED, and cursor pagination.

Here is the composite index pattern from the skill. The source says it works for queries that filter on status equality and created_at range:

What does the skill need, and what are the safety notes?

The skill needs PostgreSQL database access only if you ask the agent to run the SQL. It does not run scripts and does not use the network, according to its listing.

The configuration template uses ALTER SYSTEM and REVOKE statements. These can change a live server or lock out access if run blindly. Review every statement, test on a non-production database, and only apply server settings after you understand their effect. The skill itself is a general reference, so it is not a substitute for reviewing your specific schema.

For detailed database reviews, the skill points to the separate database-reviewer agent.

• Do not run ALTER SYSTEM or REVOKE against production without review.
• Test index changes on a copy of the data first.
• Non-PostgreSQL databases such as MySQL or SQL Server have different syntax and tuning, so this skill is not designed for them.

What tips help you get better results?

Give the agent your Postgres version, table sizes and the exact query when asking about performance. Ask for the reasoning behind an index so you can judge it. If you want a deeper audit, ask for the database-reviewer agent by name, since the skill recommends it for that work.

• Paste the actual query and the table definition.
• Ask why an index type was chosen, such as B-tree versus BRIN for time-series ranges.
• Run the anti-pattern queries on a staging database first to see the output.