Skip to content

Commit b835db4

Browse files
QSchlegelQSchlegel
authored
Merge pull request #226 from MeshJS/docs/roadmap-and-contributing
docs: add roadmap and contributing guide
2 parents b9ea7b8 + b96e8e7 commit b835db4

45 files changed

Lines changed: 2492 additions & 4 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/supabase-postgres-best-practices/AGENTS.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Supabase Postgres Best Practices
2+
3+
## Structure
4+
5+
```
6+
supabase-postgres-best-practices/
7+
SKILL.md # Main skill file - read this first
8+
AGENTS.md # This navigation guide
9+
CLAUDE.md # Symlink to AGENTS.md
10+
references/ # Detailed reference files
11+
```
12+
13+
## Usage
14+
15+
1. Read `SKILL.md` for the main skill instructions
16+
2. Browse `references/` for detailed documentation on specific topics
17+
3. Reference files are loaded on-demand - read only what you need
18+
19+
Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.
20+
21+
## When to Apply
22+
23+
Reference these guidelines when:
24+
- Writing SQL queries or designing schemas
25+
- Implementing indexes or query optimization
26+
- Reviewing database performance issues
27+
- Configuring connection pooling or scaling
28+
- Optimizing for Postgres-specific features
29+
- Working with Row-Level Security (RLS)
30+
31+
## Rule Categories by Priority
32+
33+
| Priority | Category | Impact | Prefix |
34+
|----------|----------|--------|--------|
35+
| 1 | Query Performance | CRITICAL | `query-` |
36+
| 2 | Connection Management | CRITICAL | `conn-` |
37+
| 3 | Security & RLS | CRITICAL | `security-` |
38+
| 4 | Schema Design | HIGH | `schema-` |
39+
| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
40+
| 6 | Data Access Patterns | MEDIUM | `data-` |
41+
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
42+
| 8 | Advanced Features | LOW | `advanced-` |
43+
44+
## How to Use
45+
46+
Read individual rule files for detailed explanations and SQL examples:
47+
48+
```
49+
references/query-missing-indexes.md
50+
references/schema-partial-indexes.md
51+
references/_sections.md
52+
```
53+
54+
Each rule file contains:
55+
- Brief explanation of why it matters
56+
- Incorrect SQL example with explanation
57+
- Correct SQL example with explanation
58+
- Optional EXPLAIN output or metrics
59+
- Additional context and references
60+
- Supabase-specific notes (when applicable)
61+
62+
## References
63+
64+
- https://www.postgresql.org/docs/current/
65+
- https://supabase.com/docs
66+
- https://wiki.postgresql.org/wiki/Performance_Optimization
67+
- https://supabase.com/docs/guides/database/overview
68+
- https://supabase.com/docs/guides/auth/row-level-security

‎.agents/skills/supabase-postgres-best-practices/CLAUDE.md‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
# Supabase Postgres Best Practices
2+
3+
## Structure
4+
5+
```
6+
supabase-postgres-best-practices/
7+
SKILL.md # Main skill file - read this first
8+
AGENTS.md # This navigation guide
9+
CLAUDE.md # Symlink to AGENTS.md
10+
references/ # Detailed reference files
11+
```
12+
13+
## Usage
14+
15+
1. Read `SKILL.md` for the main skill instructions
16+
2. Browse `references/` for detailed documentation on specific topics
17+
3. Reference files are loaded on-demand - read only what you need
18+
19+
Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.
20+
21+
## When to Apply
22+
23+
Reference these guidelines when:
24+
- Writing SQL queries or designing schemas
25+
- Implementing indexes or query optimization
26+
- Reviewing database performance issues
27+
- Configuring connection pooling or scaling
28+
- Optimizing for Postgres-specific features
29+
- Working with Row-Level Security (RLS)
30+
31+
## Rule Categories by Priority
32+
33+
| Priority | Category | Impact | Prefix |
34+
|----------|----------|--------|--------|
35+
| 1 | Query Performance | CRITICAL | `query-` |
36+
| 2 | Connection Management | CRITICAL | `conn-` |
37+
| 3 | Security & RLS | CRITICAL | `security-` |
38+
| 4 | Schema Design | HIGH | `schema-` |
39+
| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
40+
| 6 | Data Access Patterns | MEDIUM | `data-` |
41+
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
42+
| 8 | Advanced Features | LOW | `advanced-` |
43+
44+
## How to Use
45+
46+
Read individual rule files for detailed explanations and SQL examples:
47+
48+
```
49+
references/query-missing-indexes.md
50+
references/schema-partial-indexes.md
51+
references/_sections.md
52+
```
53+
54+
Each rule file contains:
55+
- Brief explanation of why it matters
56+
- Incorrect SQL example with explanation
57+
- Correct SQL example with explanation
58+
- Optional EXPLAIN output or metrics
59+
- Additional context and references
60+
- Supabase-specific notes (when applicable)
61+
62+
## References
63+
64+
- https://www.postgresql.org/docs/current/
65+
- https://supabase.com/docs
66+
- https://wiki.postgresql.org/wiki/Performance_Optimization
67+
- https://supabase.com/docs/guides/database/overview
68+
- https://supabase.com/docs/guides/auth/row-level-security

‎.agents/skills/supabase-postgres-best-practices/README.md‎

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
# Supabase Postgres Best Practices - Contributor Guide
2+
3+
This skill contains Postgres performance optimization references optimized for
4+
AI agents and LLMs. It follows the [Agent Skills Open Standard](https://agentskills.io/).
5+
6+
## Quick Start
7+
8+
```bash
9+
# From repository root
10+
npm install
11+
12+
# Validate existing references
13+
npm run validate
14+
15+
# Build AGENTS.md
16+
npm run build
17+
```
18+
19+
## Creating a New Reference
20+
21+
1. **Choose a section prefix** based on the category:
22+
- `query-` Query Performance (CRITICAL)
23+
- `conn-` Connection Management (CRITICAL)
24+
- `security-` Security & RLS (CRITICAL)
25+
- `schema-` Schema Design (HIGH)
26+
- `lock-` Concurrency & Locking (MEDIUM-HIGH)
27+
- `data-` Data Access Patterns (MEDIUM)
28+
- `monitor-` Monitoring & Diagnostics (LOW-MEDIUM)
29+
- `advanced-` Advanced Features (LOW)
30+
31+
2. **Copy the template**:
32+
```bash
33+
cp references/_template.md references/query-your-reference-name.md
34+
```
35+
36+
3. **Fill in the content** following the template structure
37+
38+
4. **Validate and build**:
39+
```bash
40+
npm run validate
41+
npm run build
42+
```
43+
44+
5. **Review** the generated `AGENTS.md`
45+
46+
## Skill Structure
47+
48+
```
49+
skills/supabase-postgres-best-practices/
50+
├── SKILL.md # Agent-facing skill manifest (Agent Skills spec)
51+
├── AGENTS.md # [GENERATED] Compiled references document
52+
├── README.md # This file
53+
└── references/
54+
├── _template.md # Reference template
55+
├── _sections.md # Section definitions
56+
├── _contributing.md # Writing guidelines
57+
└── *.md # Individual references
58+
59+
packages/skills-build/
60+
├── src/ # Generic build system source
61+
└── package.json # NPM scripts
62+
```
63+
64+
## Reference File Structure
65+
66+
See `references/_template.md` for the complete template. Key elements:
67+
68+
````markdown
69+
---
70+
title: Clear, Action-Oriented Title
71+
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
72+
impactDescription: Quantified benefit (e.g., "10-100x faster")
73+
tags: relevant, keywords
74+
---
75+
76+
## [Title]
77+
78+
[1-2 sentence explanation]
79+
80+
**Incorrect (description):**
81+
82+
```sql
83+
-- Comment explaining what's wrong
84+
[Bad SQL example]
85+
```
86+
````
87+
88+
**Correct (description):**
89+
90+
```sql
91+
-- Comment explaining why this is better
92+
[Good SQL example]
93+
```
94+
95+
```
96+
## Writing Guidelines
97+
98+
See `references/_contributing.md` for detailed guidelines. Key principles:
99+
100+
1. **Show concrete transformations** - "Change X to Y", not abstract advice
101+
2. **Error-first structure** - Show the problem before the solution
102+
3. **Quantify impact** - Include specific metrics (10x faster, 50% smaller)
103+
4. **Self-contained examples** - Complete, runnable SQL
104+
5. **Semantic naming** - Use meaningful names (users, email), not (table1, col1)
105+
106+
## Impact Levels
107+
108+
| Level | Improvement | Examples |
109+
|-------|-------------|----------|
110+
| CRITICAL | 10-100x | Missing indexes, connection exhaustion |
111+
| HIGH | 5-20x | Wrong index types, poor partitioning |
112+
| MEDIUM-HIGH | 2-5x | N+1 queries, RLS optimization |
113+
| MEDIUM | 1.5-3x | Redundant indexes, stale statistics |
114+
| LOW-MEDIUM | 1.2-2x | VACUUM tuning, config tweaks |
115+
| LOW | Incremental | Advanced patterns, edge cases |
116+
```

‎.agents/skills/supabase-postgres-best-practices/SKILL.md‎

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
name: supabase-postgres-best-practices
3+
description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
4+
license: MIT
5+
metadata:
6+
author: supabase
7+
version: "1.1.0"
8+
organization: Supabase
9+
date: January 2026
10+
abstract: Comprehensive Postgres performance optimization guide for developers using Supabase and Postgres. Contains performance rules across 8 categories, prioritized by impact from critical (query performance, connection management) to incremental (advanced features). Each rule includes detailed explanations, incorrect vs. correct SQL examples, query plan analysis, and specific performance metrics to guide automated optimization and code generation.
11+
---
12+
13+
# Supabase Postgres Best Practices
14+
15+
Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.
16+
17+
## When to Apply
18+
19+
Reference these guidelines when:
20+
- Writing SQL queries or designing schemas
21+
- Implementing indexes or query optimization
22+
- Reviewing database performance issues
23+
- Configuring connection pooling or scaling
24+
- Optimizing for Postgres-specific features
25+
- Working with Row-Level Security (RLS)
26+
27+
## Rule Categories by Priority
28+
29+
| Priority | Category | Impact | Prefix |
30+
|----------|----------|--------|--------|
31+
| 1 | Query Performance | CRITICAL | `query-` |
32+
| 2 | Connection Management | CRITICAL | `conn-` |
33+
| 3 | Security & RLS | CRITICAL | `security-` |
34+
| 4 | Schema Design | HIGH | `schema-` |
35+
| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
36+
| 6 | Data Access Patterns | MEDIUM | `data-` |
37+
| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
38+
| 8 | Advanced Features | LOW | `advanced-` |
39+
40+
## How to Use
41+
42+
Read individual rule files for detailed explanations and SQL examples:
43+
44+
```
45+
references/query-missing-indexes.md
46+
references/schema-partial-indexes.md
47+
references/_sections.md
48+
```
49+
50+
Each rule file contains:
51+
- Brief explanation of why it matters
52+
- Incorrect SQL example with explanation
53+
- Correct SQL example with explanation
54+
- Optional EXPLAIN output or metrics
55+
- Additional context and references
56+
- Supabase-specific notes (when applicable)
57+
58+
## References
59+
60+
- https://www.postgresql.org/docs/current/
61+
- https://supabase.com/docs
62+
- https://wiki.postgresql.org/wiki/Performance_Optimization
63+
- https://supabase.com/docs/guides/database/overview
64+
- https://supabase.com/docs/guides/auth/row-level-security

0 commit comments

Comments
 (0)