Agent Skill

Supabase Postgres Best Practices skill

supabase-postgres-best-practicessupabase/agent-skillsskills/supabase-postgres-best-practices/SKILL.md

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.

2.9kMIT

always on

182 tokname + description

once used

408 tokSKILL.md body

bundled files

3557 KB

installs

455kskills.sh

Install the Supabase Postgres Best Practices skill

Skills CLI (Claude Code, Codex, Cursor and others)

npx skills add https://github.com/supabase/agent-skills --skill supabase-postgres-best-practices

Claude Code, by hand (all projects)

git clone --depth 1 https://github.com/supabase/agent-skills.git /tmp/agent-skills
mkdir -p ~/.claude/skills
cp -R /tmp/agent-skills/skills/supabase-postgres-best-practices ~/.claude/skills/supabase-postgres-best-practices

For one project only, copy the folder into .claude/skills/ in that project instead. The agent picks it up when a task matches its description.

What it costs your context

Agent Skills load in three steps. Tokens counted with the o200k tokenizer; your model's count will differ a little.

When	What loads	Cost
Every session	Name and description	182 tok
When the agent uses it	The SKILL.md instructions	408 tok
Only if opened	35 bundled files (57 KB)	varies

Until it is used, supabase-postgres-best-practices costs about 7.5× less than the median MCP server we measured (1,362 tokens on every turn). Installing all 2 skills from supabase/agent-skills would load 367 tokens of descriptions. Skills vs MCP study

Checks

Our checks found nothing to flag: it follows the Agent Skills specification's naming and size guidelines and doesn't pipe downloads into a shell.

Checked 2026-10-22 · method

What's inside

The headings of its SKILL.md. Read the full file on GitHub.

Supabase Postgres Best Practices
When to Apply
Rule Categories by Priority
How to Use
References

More skills from supabase/agent-skills

All skills in this repo

supabasesupabase/agent-skills
Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, declarative schemas, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector); debugging and troubleshooting errors or unexpected behavior on Supabase projects (HTTP errors, Postgres errors, RLS surprises, permission denied, schema cache issues, timeouts, Edge Function crashes, Realtime drops, Storage failures) and reading or querying logs (Logs Explorer, ClickHouse).
338k185 tok idle · 3,038 in use