Kipt

Postgres best practices skill: what it does and how to install it

Supabase's postgres best practices skill gives your agent 31 rules for indexes, RLS, pooling and locking on any Postgres. What it does and how to install it.

By the Kipt team · Updated 23 October 2026

Source: supabase/agent-skills · Maintainer: Supabase · License: MIT · Checked: 23 October 2026

What is the postgres best practices skill?

The postgres best practices skill is a set of SQL rules that a coding agent reads before it writes or changes anything in a Postgres database: tables, indexes, migrations, RLS policies or slow queries. It is for developers who let Claude Code, Codex or Cursor touch their schema and want the agent to follow known Postgres patterns instead of guessing.

The skill is maintained by Supabase in supabase/agent-skills, but it is not tied to Supabase. Its description opens with: "Postgres best practices maintained by Supabase, for Postgres running anywhere." The rest of the description lists when to load it: creating or altering tables, migrations, RLS policies and their tests, indexes, triggers, functions, queues and scheduled jobs, pgvector search, restores and imports, and diagnosing slow queries, timeouts, connection exhaustion, locking or bloat. It also says schema and security tasks need the rules "even for a one-column change or a single query."

As of 23 October 2026, its skills.sh page listed about 457,000 installs.

What does it do?

The SKILL.md is a short index. It sorts the rules into eight categories ranked by impact and tells the agent to open the individual rule files for detail:

Priority Category Impact
1 Query Performance Critical
2 Connection Management Critical
3 Security and RLS Critical
4 Schema Design High
5 Concurrency and Locking Medium to high
6 Data Access Patterns Medium
7 Monitoring and Diagnostics Low to medium
8 Advanced Features Low

Each rule file follows the same shape: why it matters, an incorrect SQL example, a correct one, sometimes EXPLAIN output, and links to the Postgres or Supabase docs. For example, query-missing-indexes.md shows a sequential scan on orders turning into an index scan once customer_id is indexed, and schema-constraints.md explains that Postgres has no ADD CONSTRAINT IF NOT EXISTS, then shows a DO block that adds a constraint safely in a migration.

What's in the folder:

  • SKILL.md: the category table, when to apply the rules, and a list of reference links.
  • references/: 31 rule files, named by category prefix. Examples: conn-pooling.md, conn-prepared-statements.md, security-rls-basics.md, security-rls-performance.md, schema-foreign-key-indexes.md, lock-skip-locked.md, data-n-plus-one.md, data-pagination.md, monitor-explain-analyze.md, advanced-jsonb-indexing.md. Three more files starting with an underscore are templates and section definitions for contributors.
  • CHANGELOG.md: release notes for the skill.

There are no scripts. The agent only reads Markdown, so nothing runs against your database unless the agent itself runs SQL through another tool.

How do you install the postgres best practices skill?

The repo README gives two routes, and Supabase's AI skills docs page repeats the first.

Skills CLI (any agent). The skills CLI copies the folder into your agent's skills directory:

npx skills add supabase/agent-skills --skill supabase-postgres-best-practices

Add -g to install it for every project. For Claude Code the folder lands in .claude/skills/supabase-postgres-best-practices/ in your project, or ~/.claude/skills/supabase-postgres-best-practices/ with -g, the standard Claude Code skill locations. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

Claude Code plugin. Supabase publishes its own plugin marketplace:

claude plugin marketplace add supabase/agent-skills
claude plugin install postgres-best-practices@supabase-agent-skills

Claude Code names plugin skills /plugin-name:skill-name, so it appears as /postgres-best-practices:supabase-postgres-best-practices. Pick one route per agent, or you get the skill twice.

claude.ai. Zip the supabase-postgres-best-practices folder and upload it under Customize, then Skills, as the Claude Help Center describes. That works for reviewing SQL and schemas you paste into a chat.

How do you use it?

You rarely call it by name. The description is written so the agent loads it whenever a task touches the database, so a normal request is enough. The README's own examples include "Optimize this Postgres query" and "Help me add proper indexes to this table".

Example prompts (suggestions, not quotes from the repo):

  • "Write a migration that adds a team_id column to projects, with a foreign key and the index it needs."
  • "This query takes four seconds on 2 million rows. Here is the EXPLAIN ANALYZE output. What should change?"
  • "Add RLS policies so users can only read rows from their own organization, and keep them fast."
  • "Our serverless functions keep hitting 'too many connections'. Review how we connect to Postgres."
  • "Replace this OFFSET pagination with something that stays fast on deep pages."

There are no packages, CLIs or API keys to install. If you want the agent to run the SQL it writes and read real query plans, pair the skill with a database MCP server; the best MCP servers guide covers Supabase's server and DBHub, including their read-only modes.

Tips and limits

  • Any Postgres, with Supabase notes. Most rules are plain Postgres. Some files add Supabase-specific notes, and the description mentions extensions like pg_cron, pgmq and pgvector. Check that your host supports an extension before you rely on advice about it.
  • The description is broader than the folder. The description names topics such as pgvector, pg_restore and queues, while the 31 rule files concentrate on the eight categories above. For those extra topics, the agent falls back on the linked docs and its own knowledge.
  • Rules, not a linter. The skill guides what the agent writes. It does not scan an existing database or block a bad migration. Review migrations as you would any other change.
  • Security audits. As of 23 October 2026, skills.sh showed Gen Agent Trust Hub, Socket and Snyk all as Pass for this skill. It ships no executables.
  • License. The repo is MIT licensed, so you can fork the rules and add your team's own conventions as new rule files.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and its files, including the references folder; for a repo with several skills, like this one, it shows a list to pick from. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Supabase.

Similar skills

  • API design skill: Addy Osmani's rules for the interface that sits in front of your database.
  • Stripe skill: Stripe's official best practices for payments, webhooks and API keys, for the billing side of the same app.
  • Best MCP servers: the Supabase and DBHub servers that let an agent run the SQL this skill shapes.
  • Best Claude Code skills: a wider list to browse.

Questions

What is the postgres best practices skill?

supabase-postgres-best-practices is an Agent Skill maintained by Supabase. It gives a coding agent 31 short rule files on query performance, connection management, Row-Level Security, schema design, locking, data access and monitoring, each with an incorrect and a correct SQL example.

Do I need Supabase to use the postgres best practices skill?

No. The skill's description says it is for Postgres running anywhere, and most rules are plain Postgres advice. Some rule files add Supabase-specific notes, and a few topics in the description, such as pg_cron and pgmq, depend on extensions your host may or may not offer.

How do I install the Supabase postgres skill in Claude Code?

Run npx skills add supabase/agent-skills --skill supabase-postgres-best-practices, or add Supabase's plugin marketplace with claude plugin marketplace add supabase/agent-skills and then run claude plugin install postgres-best-practices@supabase-agent-skills.

Does the skill connect to my database?

No. It is Markdown only: a SKILL.md and a references folder of rule files. It ships no scripts and needs no credentials. To let an agent query a database you would add an MCP server, such as Supabase's, separately.

Is the postgres best practices skill free to use?

Yes. The supabase/agent-skills repo is under the MIT License, so you can use, copy and edit the rules as long as you keep the copyright notice.

More in Skill directory

All guides

Keep your prompts and skills in one place, in your own GitHub. Install every skill with one command.

Get started

Kipt is an independent product, not affiliated with or endorsed by Anthropic, OpenAI, Cursor or GitHub. Claude, ChatGPT, Codex, Cursor and GitHub are trademarks of their owners.