New: 98,000+ skills indexed from GitHub repos with 100+ stars · every skill safety-checkedBrowse top skillsTop skills
Esc to closeBrowse all skills
Submit a skillBrowse skills
Submit a skillBrowse skills

Official agent skill

Supabase Postgres Best Practices

by supabase in supabase/agent-skills

Gives the agent Postgres rules to consult before writing or changing tables, queries, indexes, RLS policies or migrations, and when diagnosing slow queries.

OfficialMITAuto-check passedDatabases

Install Supabase Postgres Best Practices

skills CLI
$ npx skills add supabase/agent-skills --skill supabase-postgres-best-practices -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install supabase/agent-skills supabase-postgres-best-practices --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/supabase/agent-skills.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/supabase-postgres-best-practices .claude/skills/supabase-postgres-best-practices && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
supabase-postgres-best-practices
GitHub stars
2.7k
Used in
24 other repos
Token cost
~808 tokens
SKILL.md length
166 words
Files
36 (incl. references)
Skills in repo
2
Repo updated
First seen
Licence
MIT

At a glance

Gives the agent Postgres rules to consult before writing or changing tables, queries, indexes, RLS policies or migrations, and when diagnosing slow queries.

  • Designing or altering tables, columns and indexes in Postgres
  • SKILL.md covers When to Apply, Rule Categories by Priority, How to Use and References
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md
  • Writing row-level security policies and the tests that verify them

What it does

The skill is a rule library for Postgres, maintained by Supabase and meant for Postgres running anywhere. The agent is asked to load it before writing or changing anything that lives in a Postgres database: tables and column types, schema design, migrations and declarative schema files, row-level security policies and their tests, indexes, triggers, functions, queues and scheduled jobs such as pg_cron and pgmq, pgvector search, and restoring dumps with pg_restore.

Rules are grouped into eight categories ranked by impact. Query performance, connection management and security with RLS come first, followed by schema design, concurrency and locking, data access patterns, monitoring and diagnostics, and advanced features. Each rule is its own file under references, with a short explanation, an incorrect and a correct SQL example, optional EXPLAIN output and Supabase-specific notes, and the agent reads only the files it needs.

It also applies when diagnosing slow queries, high CPU, timeouts, connection exhaustion, locking, bloat or rows visible to the wrong user, and the description stresses that even a one-column change or a single query benefits from the rules. A changelog ships alongside the reference files.

When your agent uses it

  • Designing or altering tables, columns and indexes in Postgres
  • Writing row-level security policies and the tests that verify them
  • Diagnosing slow queries, locking or connection exhaustion
  • Writing migrations or importing data into a Postgres database
  • Setting up queues or scheduled jobs with pg_cron or pgmq

Example prompts

  • “Add a nullable archived_at column to the orders table and tell me which index it needs.”
  • “This query takes eight seconds. Read the EXPLAIN output and suggest what to change.”
  • “Write RLS policies so each tenant only sees its own rows in the invoices table.”

What it can do on your machine

Read from SKILL.md and the folder at commit c9be0e9. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • supabase.com
    • postgresql.org
    • wiki.postgresql.org

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Supabase Postgres Best Practices loads about 808 tokens when it runs, and up to ~14k if it reads all its reference files. Until then it costs about 217 tokens; SKILL.md has 166 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~217
When it runs · the whole SKILL.md, loaded when a task matches
~808
With references · SKILL.md plus every file in references/, read only if the agent opens them
~14k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from supabase/agent-skills at commit c9be0e9, republished under its MIT licence (© supabase). 166 words, ~808 tokens.

Download SKILL.mdSave it as .claude/skills/supabase-postgres-best-practices/SKILL.md (or your agent's skills folder). This skill also uses 35 other files; get the full folder from GitHub.
name
supabase-postgres-best-practices
description
Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pg_cron, pgmq), vector/semantic search (pgvector), and restoring dumps (pg_restore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.
license
MIT
metadata.author
supabase
metadata.version
1.1.1
metadata.organization
Supabase
metadata.date
January 2026
metadata.abstract
Comprehensive Postgres performance optimization guide for developers using Supabase and Postgres. Contains performance rules across 8 categories, prioritized…

Supabase Postgres Best Practices

Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.

When to Apply

Reference these guidelines when:

  • Writing SQL queries or designing schemas
  • Implementing indexes or query optimization
  • Reviewing database performance issues
  • Configuring connection pooling or scaling
  • Optimizing for Postgres-specific features
  • Working with Row-Level Security (RLS)

Rule Categories by Priority

PriorityCategoryImpactPrefix
1Query PerformanceCRITICALquery-
2Connection ManagementCRITICALconn-
3Security & RLSCRITICALsecurity-
4Schema DesignHIGHschema-
5Concurrency & LockingMEDIUM-HIGHlock-
6Data Access PatternsMEDIUMdata-
7Monitoring & DiagnosticsLOW-MEDIUMmonitor-
8Advanced FeaturesLOWadvanced-

How to Use

Read individual rule files for detailed explanations and SQL examples:

references/query-missing-indexes.md
references/query-partial-indexes.md
references/_sections.md

Each rule file contains:

  • Brief explanation of why it matters
  • Incorrect SQL example with explanation
  • Correct SQL example with explanation
  • Optional EXPLAIN output or metrics
  • Additional context and references
  • Supabase-specific notes (when applicable)

References

© supabase, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 35 other files (references) in skills/supabase-postgres-best-practices of supabase/agent-skills.

  • SKILL.md
  • CHANGELOG.md
  • references/_contributing.md
  • references/_sections.md
  • references/_template.md
  • references/advanced-full-text-search.md
  • references/advanced-jsonb-indexing.md
  • references/conn-idle-timeout.md
  • references/conn-limits.md
  • references/conn-pooling.md
  • references/conn-prepared-statements.md
  • references/data-batch-inserts.md
  • references/data-n-plus-one.md
  • references/data-pagination.md
  • references/data-upsert.md
  • references/lock-advisory.md
  • references/lock-deadlock-prevention.md
  • references/lock-short-transactions.md
  • references/lock-skip-locked.md
  • references/monitor-explain-analyze.md
  • … and 16 more

Open the folder on GitHubat commit c9be0e9

Used in at least 24 other repositories

We found 53 copies of this SKILL.md (exact, near-identical or edited) in other folders, from 24 other GitHub owners. This page covers the copy in supabase/agent-skills, which our catalogue first saw on October 7, 2026.

…and 3 more copies not listed here.

Compare with similar skills

Supabase Postgres Best Practices next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Supabase Postgres Best Practices compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Supabase Postgres Best Practices this skillsupabase/agent-skills2.7k24 repos~808Automated safety check: PassMIT
DatabasesMicrock/ordinary-claude-skills403—~1.9kAutomated safety check: NotesMIT
DB ContextSilvioBaratto/optimizer176—~6.4kAutomated safety check: NotesCustom licence
Expert DatabaseReJeCtAll/ExpertTeam-Codex113—~692Automated safety check: PassMIT
Postgrestimescale/pg-aiguide1.9k—~941Automated safety check: PassApache-2.0
Database Domain Specialistmodu-ai/moai-adk1.2k—~2.8kAutomated safety check: PassApache-2.0

Similar skills

  • Databases

    Microck/ordinary-claude-skills

    Work with MongoDB (document database, BSON documents, aggregation pipelines, Atlas cloud) and PostgreSQL (relational database, SQL queries, psql CLI, pgAdmin).

    403 GitHub stars~1.9k tokensUpdated 1 mo ago
    DatabasesAuto-check: notes

  • DB Context

    SilvioBaratto/optimizer

    Complete knowledge of the optimizer PostgreSQL database: 57 ingestion tables, schema, relationships, live row counts, query patterns, and conventions.

    176 GitHub stars~6.4k tokensUpdated today
    DatabasesAuto-check: notes

  • Expert Database

    ReJeCtAll/ExpertTeam-Codex

    数据库优化专家入口。用于 Codex CLI 的 $expert-database 调用. An agent skill from ReJeCtAll/ExpertTeam-Codex.

    113 GitHub stars~692 tokensUpdated 3 mo ago
    DatabasesAuto-check passed

  • Postgres

    timescale/pg-aiguide

    A skill your agent uses for any PostgreSQL database work — table design, indexing, data types, constraints, extensions (pgvector, PostGIS, TimescaleDB), search, and migrations.

    1.9k GitHub stars~941 tokensUpdated today
    DatabasesAuto-check passed

  • Database Domain Specialist

    modu-ai/moai-adk

    Database guidance for PostgreSQL, MongoDB, Redis and Oracle plus Neon, Supabase and Firestore: schema design, indexing, query tuning and cloud database choice.

    1.2k GitHub stars~2.8k tokensUpdated today
    DatabasesAuto-check passed

  • PostgreSQL Pro

    Jeffallan/claude-skills

    Tunes and administers PostgreSQL: EXPLAIN-driven query tuning, index choice, JSONB, extensions, streaming or logical replication, VACUUM and pg_stat monitoring.

    12k GitHub stars~1.5k tokensUpdated 4 days ago
    DatabasesAuto-check passed

More from supabase/agent-skills

  • Supabase Development and Debugging

    supabase/agent-skills

    Official

    General Supabase skill for database, auth, Edge Functions, Realtime and storage work, plus client libraries, migrations, security audits, debugging and reading logs.

    2.7k GitHub starsUsed in 3 repos~3.6k tokens
    Auto-check passed

Works with

Categories

Questions about Supabase Postgres Best Practices

What does Supabase Postgres Best Practices do?

Gives the agent Postgres rules to consult before writing or changing tables, queries, indexes, RLS policies or migrations, and when diagnosing slow queries. The skill is a rule library for Postgres, maintained by Supabase and meant for Postgres running anywhere. The agent is asked to load it before writing or changing anything that lives in a Postgres database: tables and column types, schema design, migrations and declarative schema files, row-level security policies and their tests, indexes, triggers, functions, queues and scheduled jobs such as pg_cron and pgmq, pgvector search, and restoring dumps with pg_restore.

When should I use Supabase Postgres Best Practices?

Supabase Postgres Best Practices fits situations like: designing or altering tables, columns and indexes in Postgres; writing row-level security policies and the tests that verify them; diagnosing slow queries, locking or connection exhaustion; writing migrations or importing data into a Postgres database.

How do I install Supabase Postgres Best Practices in Claude Code?

Run `npx skills add supabase/agent-skills --skill supabase-postgres-best-practices -a claude-code`. Or copy the skill folder (skills/supabase-postgres-best-practices in supabase/agent-skills) into .claude/skills/supabase-postgres-best-practices in your project. Claude Code loads it when a task matches its description.

How do I install Supabase Postgres Best Practices in Codex?

Run `npx skills add supabase/agent-skills --skill supabase-postgres-best-practices -a codex`. Or copy the skill folder (skills/supabase-postgres-best-practices in supabase/agent-skills) into .agents/skills/supabase-postgres-best-practices in your project. Codex loads it when a task matches its description.

Can I use Supabase Postgres Best Practices in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add supabase/agent-skills --skill supabase-postgres-best-practices -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/supabase-postgres-best-practices, .gemini/skills/supabase-postgres-best-practices, .github/skills/supabase-postgres-best-practices and .opencode/skills/supabase-postgres-best-practices in your project.

What does Supabase Postgres Best Practices need to run?

SKILL.md names no scripts, command-line tools or credentials: Supabase Postgres Best Practices is instructions for the agent only.

Does Supabase Postgres Best Practices access the network?

SKILL.md names 3 domains. As links in the text: supabase.com, postgresql.org and wiki.postgresql.org. This is read from the text; nothing was executed.

Is Supabase Postgres Best Practices safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Supabase Postgres Best Practices use?

Supabase Postgres Best Practices is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Supabase Postgres Best Practices use?

About 808 tokens (SKILL.md is roughly 3.2k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 13k tokens, read only when the agent opens those files.

What are the alternatives to Supabase Postgres Best Practices?

Skills that share tags, products or a category with Supabase Postgres Best Practices: Databases (Microck/ordinary-claude-skills, 403 stars), DB Context (SilvioBaratto/optimizer, 176 stars), Expert Database (ReJeCtAll/ExpertTeam-Codex, 113 stars) and Postgres (timescale/pg-aiguide, 1.9k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Supabase Postgres Best Practices?

supabase (a GitHub organization, an official publisher) maintains it in supabase/agent-skills, which has 2,708 GitHub stars. The repository holds 2 skills in this directory. The repository was last updated on October 2, 2026.

Source: supabase/agent-skills on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.