CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

88

1.25x
Quality

84%

Does it follow best practices?

Impact

95%

1.25x

Average score across 3 eval scenarios

SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

Quality

Content

68%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.

A well-structured hub skill: the body stays lean, defers all SQL detail to 35 one-level-deep reference files, and communicates rule priorities through a compact table. Its weaknesses are incomplete navigation (only 3 of 35 rule files named, no task-to-file mapping beyond prefixes) and the absence of any validation/verification checkpoint in the workflow, which the rubric caps at 3 for database skills.

Suggestions

Replace the three arbitrary example paths in 'How to Use' with a complete task-to-file mapping, e.g. 'Writing or reviewing a query? Read references/query-*.md; designing a table? references/schema-*.md', so Claude can locate the right rule file without guessing from prefixes.

Add a verification step to the workflow, such as 'After applying a fix, confirm the improvement with EXPLAIN ANALYZE (see references/monitor-explain-analyze.md)' — the rubric expects a feedback loop for database operations and currently caps workflow clarity at 3 for its absence.

Drop references/_sections.md from the 'How to Use' block (it is an internal section-definitions file, not a rule file) and instead explain the filename prefix convention explicitly, e.g. one line noting that every rule file is named <prefix>-<topic>.md per the category table.

DimensionReasoningScore

Conciseness

The body is lean and assumes Claude's competence: a two-line overview, six 'when to apply' bullets, an 8-row priority table, and a short file-usage explanation with external links. Nothing explains Postgres basics Claude already knows, and every section carries information (priorities, prefixes, file layout) that is not derivable from the description. It matches the top anchor 'every token earns its place'; 4 would require over-explanation worth trimming, and none is present.

5 / 5

Actionability

The navigation mechanism is partially concrete — the category table maps tasks to filename prefixes ("query-", "conn-", "security-"...) and the file inventory in references/ matches — but the body gives no executable SQL or commands itself and the 'How to Use' code block names only 3 of the 35 rule files, with no instruction for mapping a task to the right file or a complete index. It sits at 'some concrete guidance but incomplete; missing key details' rather than 4, which would require the lookup guidance to be complete with only minor gaps.

3 / 5

Workflow Clarity

The implied sequence (identify the task category → read the matching rule files → apply the incorrect/correct patterns) is present via the table and 'How to Use', but steps are never explicitly ordered and there are no validation checkpoints, e.g. no 'verify the fix with EXPLAIN ANALYZE' loop. Per the rubric's scoring notes, database-operation skills missing feedback loops are capped at 3; it is not 2 because the table-plus-prefix structure does convey a usable rough sequence.

3 / 5

Progressive Disclosure

The bundle structure is genuinely good: SKILL.md is a short overview, all detail lives in one-level-deep references/*.md rule files (verified to exist), and the prefix convention makes files discoverable. It falls short of 5 because the body points to only three arbitrarily chosen files out of 35 and includes _sections.md (an internal section-definitions file) in the 'How to Use' block without explaining it, leaving navigation partially implicit — 'references mostly clear; minor organization gaps'.

4 / 5

Total

15

/

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.

An exemplary skill description: it explicitly states both what it provides (Postgres best-practice rules for schema, security, and SQL authoring) and when to load it, front-loading trigger terms that mirror real user phrasing including specific tool names. Its length is dense with concrete triggers rather than padded fluff. No changes needed.

DimensionReasoningScore

Specificity

The description enumerates many concrete capability domains — "creating or altering tables and columns (including choosing column types)", "migrations and declarative schema files", "RLS policies and the tests that verify them", "queues and scheduled jobs (pg_cron, pgmq)", "vector/semantic search (pgvector)", "restoring dumps (pg_restore)" — with comprehensive coverage of both authoring and diagnostic tasks. It names specific tools and operations rather than abstract language; score 4's "minor gaps in coverage" does not apply since no significant Postgres task area is missing.

5 / 5

Completeness

Both questions are explicitly answered: what — "Postgres best practices maintained by Supabase... schema, migration, security, and SQL authoring tasks need these rules too"; when — "Load this skill BEFORE writing or changing anything that lives in a Postgres database" and "Also load it when diagnosing slow queries, high CPU, timeouts...". Concrete trigger phrases accompany both, matching the 5 anchor exactly; 4 would require the 'when' to be less explicit, which it is not.

5 / 5

Trigger Term Quality

Natural user phrasing is comprehensively covered: "slow queries", "high CPU", "timeouts", "EXPLAIN plans", "connection exhaustion", "locking", "bloat", "migrations", "indexes", "importing data", plus tool names (pg_cron, pgmq, pgvector, pg_restore). These are exactly the words a developer would say when needing this skill; nothing common is missing, matching the top anchor.

5 / 5

Distinctiveness Conflict Risk

It occupies a clear niche (Postgres/Supabase database work) with distinct triggers — "rows visible to the wrong user or tenant", "pg_restore", "RLS policies" — that no generic document or general-coding skill would claim. The scope clarification "for Postgres running anywhere" further sharpens boundaries rather than blurring them; conflict risk is minimal.

5 / 5

Total

20

/

20

Passed

Validation

100%

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
Reviewed

Table of Contents

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.