skills/supabase-postgres-best-practices
1
0
Fork 0
mirror of https://github.com/supabase/agent-skills.git synced 2026-01-26 19:09:51 +08:00
Code Issues Packages Projects Releases Wiki Activity

Dremove installation step

Browse Source
This commit is contained in:
Pedro Rodrigues
2026-01-16 15:17:10 +07:00
parent 4000ac7107
commit 9ac9bcc495
2 changed files with 45 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
AGENTS.md
View File

@@ -1,10 +1,13 @@
# AGENTS.md # AGENTS.md
This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot, etc.) when working with code in this repository. This file provides guidance to AI coding agents (Claude Code, Cursor, Copilot,
etc.) when working with code in this repository.
## Repository Overview ## Repository Overview
A collection of PostgreSQL best practices skills for Claude.ai and Claude Code, maintained by Supabase. Skills are packaged instructions that extend agent capabilities for database optimization. A collection of PostgreSQL best practices skills for Claude.ai and Claude Code,
maintained by Supabase. Skills are packaged instructions that extend agent
capabilities for database optimization.
## Creating a New Rule ## Creating a New Rule
@@ -30,13 +33,15 @@ packages/
### Naming Conventions ### Naming Conventions
- **Rule files**: `{prefix}-{kebab-case-name}.md` (e.g., `query-missing-indexes.md`) - **Rule files**: `{prefix}-{kebab-case-name}.md` (e.g.,
- **Prefixes determine section**: `query-`, `conn-`, `schema-`, `lock-`, `security-`, `data-`, `monitor-`, `advanced-` `query-missing-indexes.md`)
- **Prefixes determine section**: `query-`, `conn-`, `schema-`, `lock-`,
`security-`, `data-`, `monitor-`, `advanced-`
- **Special files**: Prefixed with `_` (e.g., `_template.md`, `_sections.md`) - **Special files**: Prefixed with `_` (e.g., `_template.md`, `_sections.md`)
### Rule File Format ### Rule File Format
```markdown ````markdown
--- ---
title: Clear, Action-Oriented Title title: Clear, Action-Oriented Title
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
@@ -54,6 +59,7 @@ tags: relevant, keywords
-- Comment explaining what's wrong -- Comment explaining what's wrong
[Bad SQL example] [Bad SQL example]
``` ```
````
**Correct (description):** **Correct (description):**
@@ -65,8 +71,8 @@ tags: relevant, keywords
**Supabase Note:** [Optional platform-specific guidance] **Supabase Note:** [Optional platform-specific guidance]
Reference: [Link](url) Reference: [Link](url)
```
````
### Best Practices for Context Efficiency ### Best Practices for Context Efficiency
Skills are loaded on-demand. To minimize context usage: Skills are loaded on-demand. To minimize context usage:
@@ -86,38 +92,33 @@ cd packages/postgresql-best-practices-build
npm install npm install
npm run validate # Check rule format npm run validate # Check rule format
npm run build # Generate AGENTS.md npm run build # Generate AGENTS.md
``` ````
### Impact Levels ### Impact Levels
| Level | Improvement | Examples | | Level | Improvement | Examples |
|-------|-------------|----------| | ----------- | ----------- | -------------------------------------- |
| CRITICAL | 10-100x | Missing indexes, connection exhaustion | | CRITICAL | 10-100x | Missing indexes, connection exhaustion |
| HIGH | 5-20x | Wrong index types, poor partitioning | | HIGH | 5-20x | Wrong index types, poor partitioning |
| MEDIUM-HIGH | 2-5x | N+1 queries, RLS optimization | | MEDIUM-HIGH | 2-5x | N+1 queries, RLS optimization |
| MEDIUM | 1.5-3x | Redundant indexes, stale statistics | | MEDIUM | 1.5-3x | Redundant indexes, stale statistics |
| LOW-MEDIUM | 1.2-2x | VACUUM tuning, config tweaks | | LOW-MEDIUM | 1.2-2x | VACUUM tuning, config tweaks |
| LOW | Incremental | Advanced patterns, edge cases | | LOW | Incremental | Advanced patterns, edge cases |
### File Prefix to Section Mapping ### File Prefix to Section Mapping
| Prefix | Section | Priority | | Prefix | Section | Priority |
|--------|---------|----------| | ----------- | ------------------------ | --------------- |
| `query-` | Query Performance | 1 (CRITICAL) | | `query-` | Query Performance | 1 (CRITICAL) |
| `conn-` | Connection Management | 2 (CRITICAL) | | `conn-` | Connection Management | 2 (CRITICAL) |
| `schema-` | Schema Design | 3 (HIGH) | | `schema-` | Schema Design | 3 (HIGH) |
| `lock-` | Concurrency & Locking | 4 (MEDIUM-HIGH) | | `lock-` | Concurrency & Locking | 4 (MEDIUM-HIGH) |
| `security-` | Security & RLS | 5 (MEDIUM-HIGH) | | `security-` | Security & RLS | 5 (MEDIUM-HIGH) |
| `data-` | Data Access Patterns | 6 (MEDIUM) | | `data-` | Data Access Patterns | 6 (MEDIUM) |
| `monitor-` | Monitoring & Diagnostics | 7 (LOW-MEDIUM) | | `monitor-` | Monitoring & Diagnostics | 7 (LOW-MEDIUM) |
| `advanced-` | Advanced Features | 8 (LOW) | | `advanced-` | Advanced Features | 8 (LOW) |
### End-User Installation ### End-User Installation
**Claude Code:** **claude.ai:** Add the skill to project knowledge or paste SKILL.md contents
```bash into the conversation.
npx add-skill supabase/postgres-best-practices
```
**claude.ai:**
Add the skill to project knowledge or paste SKILL.md contents into the conversation.

21
README.md
View File

@@ -1,6 +1,7 @@
# Agent Skills # Agent Skills
A collection of skills for AI coding agents. Skills are packaged instructions and scripts that extend agent capabilities. A collection of skills for AI coding agents. Skills are packaged instructions
and scripts that extend agent capabilities.
Skills follow the [Agent Skills](https://agentskills.io/) format. Skills follow the [Agent Skills](https://agentskills.io/) format.
@@ -8,9 +9,11 @@ Skills follow the [Agent Skills](https://agentskills.io/) format.
### postgresql-best-practices ### postgresql-best-practices
PostgreSQL performance optimization guidelines from Supabase. Contains rules across 8 categories, prioritized by impact. PostgreSQL performance optimization guidelines from Supabase. Contains rules
across 8 categories, prioritized by impact.
**Use when:** **Use when:**
- Writing SQL queries or designing schemas - Writing SQL queries or designing schemas
- Implementing indexes or query optimization - Implementing indexes or query optimization
- Reviewing database performance issues - Reviewing database performance issues
@@ -18,6 +21,7 @@ PostgreSQL performance optimization guidelines from Supabase. Contains rules acr
- Working with Row-Level Security (RLS) - Working with Row-Level Security (RLS)
**Categories covered:** **Categories covered:**
- Query Performance (Critical) - Query Performance (Critical)
- Connection Management (Critical) - Connection Management (Critical)
- Schema Design (High) - Schema Design (High)
@@ -27,23 +31,21 @@ PostgreSQL performance optimization guidelines from Supabase. Contains rules acr
- Monitoring & Diagnostics (Low-Medium) - Monitoring & Diagnostics (Low-Medium)
- Advanced Features (Low) - Advanced Features (Low)
## Installation
```bash
npx add-skill supabase/postgres-best-practices
```
## Usage ## Usage
Skills are automatically available once installed. The agent will use them when relevant tasks are detected. Skills are automatically available once installed. The agent will use them when
relevant tasks are detected.
**Examples:** **Examples:**
``` ```
Optimize this PostgreSQL query Optimize this PostgreSQL query
``` ```
``` ```
Review my schema for performance issues Review my schema for performance issues
``` ```
``` ```
Help me add proper indexes to this table Help me add proper indexes to this table
``` ```
@@ -51,6 +53,7 @@ Help me add proper indexes to this table
## Skill Structure ## Skill Structure
Each skill contains: Each skill contains:
- `SKILL.md` - Instructions for the agent - `SKILL.md` - Instructions for the agent
- `AGENTS.md` - Compiled rules document (generated) - `AGENTS.md` - Compiled rules document (generated)
- `rules/` - Individual rule files - `rules/` - Individual rule files