Supabase Postgres Performance Guide
Helps AI agents optimize Postgres queries, schema designs, and database configuration.
The skill mainly provides SQL guidance, with no evidence of credential theft, covert exfiltration, or malicious code. However, examples include ALTER SYSTEM, timeout, and connection-limit changes without user confirmation, environment-impact warnings, or rollback steps; data-flow and sensitive-data handling are not systematically disclosed. The MIT license and official-source references support attribution, but publisher identity is unverified and maintenance ownership is unclear, so points are deducted.
SKILL.md defines clear trigger scenarios, rule prefixes, and reference structure, while repository CI and sanity tests verify installation paths. The tests do not cover the skill's SQL behavior, abnormal inputs, or database execution, and the manifest version conflicts with the changelog (1.1.1 versus 1.4.0). Some configuration examples and formulas lack controlled, diagnosable failure guidance. Static evidence limits the score to 10 or below.
The audience, Postgres/Supabase scenarios, and eight topic categories are clearly described, with reasonably specific semantic triggers. Non-fit boundaries, input/output expectations, and conditions requiring environment-specific EXPLAIN validation are not defined, and there is no evidence of Chinese-language support. The core function is local documentation, so no additional deduction is made for overseas-service reachability, though reference-link reachability is unspecified.
The materials provide layered documentation, naming conventions, a template, examples, an MIT license, version metadata, a changelog, installation instructions, and CI. However, the selected skill's metadata is behind the changelog, maintenance ownership and update path are not explicit, troubleshooting and known limitations are sparse, and some claims depend on the broader references set not fully evidenced here.
Several rules include incorrect/correct SQL, index, and configuration examples that can directly support common optimization tasks, and installation guidance is usable. However, only a small subset of rules is shown, so the claimed eight-category coverage cannot be verified; quantified benefits lack execution evidence, and connection examples require substantial environment review. Static calibration limits effectiveness to 7 or below.
The skill cites auditable primary materials from PostgreSQL and Supabase, and the repository includes CI and installation sanity tests. It lacks tests for rule correctness, real EXPLAIN output, or third-party execution evidence; performance figures are primarily author claims, and the complete rule set is not shown. This supports limited traceability only, so the score remains at 5 or below.
- Before applying ALTER SYSTEM, timeout, or max_connections examples, confirm privileges, production impact, existing settings, and rollback procedures.
- Treat claims such as 10x or 100x performance improvement as unverified; validate them with EXPLAIN and benchmarks under the target data, version, and workload.
- Reconcile the 1.1.1 version in SKILL.md with the 1.4.0 changelog and confirm that the complete references set matches the assessed revision.
What it does & when to use it
This skill is a Supabase-maintained guide to Postgres performance optimization for developers using Supabase and Postgres. It covers eight priority-ranked areas: query performance, connection management, security and RLS, schema design, concurrency and locking, data access patterns, monitoring and diagnostics, and advanced features. Individual rules include rationale, incorrect and correct SQL examples, and may include query-plan analysis, performance metrics, and Supabase-specific notes. It fits teams that want agent-assisted Postgres query review and schema optimization.
Directs an AI agent to read rule files under references/ and review SQL queries, indexes, schema designs, connection pooling, Postgres features, and Row-Level Security against the guide’s eight rule categories. It uses incorrect-versus-correct SQL examples and, where available, EXPLAIN output, metrics, and Supabase-specific guidance to inform recommendations.
- A developer is writing a Postgres query and wants to check indexing and execution performance.
- A database engineer is designing or reviewing a Supabase schema.
- A team is investigating slow queries, connection-management issues, or locking problems.
- A developer is configuring Row-Level Security and wants a Supabase-aware review.
- A team needs to assess Postgres-specific data-access patterns or database configuration.
Pros & cons
- Covers eight Postgres performance and design areas ranked by impact.
- Rules include incorrect and correct SQL examples, with query plans and performance metrics where available.
- Explicitly addresses Supabase contexts such as RLS, connection pooling, and Postgres-specific features.
- Released under the MIT license.
- Its scope is Supabase/Postgres best practices, not the repository’s broader Supabase development skill.
- The source provides no test suite, runtime scripts, or detailed platform-validation matrix.
- Rule details live in separate reference files, and the supplied material does not show every rule.
How to install
Install the full repository with npx skills add supabase/agent-skills. Install only this skill with npx skills add supabase/agent-skills --skill supabase-postgres-best-practices. The README also documents installation as a Claude Code plugin.
How to use
After installation, use it for relevant requests such as Optimize this Postgres query, Review my schema for performance issues, or Help me add proper indexes to this table. Client-specific details beyond the documented automatic discovery behavior are not specified in the source.