Name: supabase-postgres-best-practices
Rating: 86.2 (1 reviews)
Author: supabase

supabase-postgres-best-practices

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.

1.25x

Quality

80%

Does it follow best practices?

Impact

95%

1.25x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Quality

Content

61%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The body is a well-organized, token-efficient index that points cleanly into a rich one-level-deep reference bundle. Its weaknesses are that it provides no inline executable SQL or commands and lacks an explicit workflow with validation checkpoints for the destructive/batch database operations it governs.

Suggestions

Add a brief inline 'Quick start' example (one correct vs. incorrect SQL snippet) so the body is actionable on its own, not only as a file index.

Include a short validation step in the workflow for destructive/batch tasks (e.g., 'run EXPLAIN before/after; verify migration in a transaction and test RLS policies'), which would lift workflow clarity past the cap at 3.

Replace the 3-file example list with a generated index of all rule files (or a clear statement that files map 1:1 to the prefix table) so navigation does not depend on inferring filenames.

Dimension	Reasoning	Score
Conciseness	The body is lean — a priority table, a tight bullet list, a short 'How to Use' section, and links — with no padding or explanation of concepts Claude already knows; the only minor redundancy is the opening line restating '8 categories prioritized by impact' already conveyed by the table.	4 / 5
Actionability	The body offers concrete navigation (specific file paths like 'references/query-missing-indexes.md' and a prefix convention) but no executable SQL or commands inline — all actual rule content is delegated to reference files, leaving the body itself as an index rather than actionable instruction.	3 / 5
Workflow Clarity	A rough usage pattern exists ('When to Apply' then 'How to Use: read individual rule files') but there is no sequenced workflow with validation checkpoints; given the skill governs destructive/batch database operations (migrations, schema changes) the missing feedback-loop cap applies.	3 / 5
Progressive Disclosure	Good structure: a priority/impact table organizes the 8 categories, references are one level deep, and the prefix convention aids discovery; only a few of the 32 reference files are explicitly named, so navigation relies partly on convention rather than a complete file index.	4 / 5
	Total	14 / 20 Passed

Description

100%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is exemplary: it states a clear niche, enumerates concrete capabilities and tools, and gives explicit load-time and diagnostic triggers covering both what and when. It avoids fluff and over-claims while remaining comprehensive.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — 'creating or altering tables and columns', '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)', 'restoring dumps (pg_restore)' — giving comprehensive coverage of the domain.	5 / 5
Completeness	Explicitly answers both what ('Postgres best practices ... schema, migration, security, and SQL authoring tasks need these rules too') and when with concrete trigger phrases ('Load this skill BEFORE writing or changing anything that lives in a Postgres database', 'Also load it when diagnosing ...').	5 / 5
Trigger Term Quality	Includes natural diagnostic phrases users actually say — 'slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant' — alongside task terms like 'migrations', 'RLS policies', 'indexes', covering synonyms and tool names (pg_cron, pgmq, pgvector).	5 / 5
Distinctiveness Conflict Risk	Clear niche (Supabase-maintained Postgres best practices) with Postgres-specific triggers (RLS, pgvector, pg_cron, pg_restore, EXPLAIN plans) making conflict with unrelated skills minimal.	5 / 5
	Total	20 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: supabase/agent-skills
Path: skills/supabase-postgres-best-practices/SKILL.md
Commit: 8331f91

Reviewed: 20 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.