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