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

new structure

Browse Source
This commit is contained in:
Pedro Rodrigues
2026-01-26 17:13:29 +00:00
parent eb5bd9cddd
commit 488ac5267a
16 changed files with 755 additions and 534 deletions
Download Patch File Download Diff File Expand all files Collapse all files

109
skills/supabase/AGENTS.md Normal file
View File

@@ -0,0 +1,109 @@
# Using Supabase
**Version 1.0.0**
Supabase
January 2026
> This document is optimized for AI agents and LLMs. Rules are prioritized by performance impact.
---
## Abstract
Comprehensive Supabase development guide for building applications with Supabase services. Contains guides across 8 categories covering Auth, Database, Storage, Edge Functions, Realtime, client libraries, CLI, and tooling. Each reference includes setup instructions, code examples, common mistakes, and integration patterns.
---
## Table of Contents
1. [Getting Started](#getting-started) - **CRITICAL**
2. [Auth](#auth) - **CRITICAL**
3. [Database](#database) - **CRITICAL**
4. [Storage](#storage) - **HIGH**
5. [Edge Functions](#edge-functions) - **HIGH**
6. [Realtime](#realtime) - **MEDIUM-HIGH**
7. [Client Libraries](#client-libraries) - **MEDIUM**
8. [CLI & Tools](#cli-tools) - **LOW-MEDIUM**
---
## 1. Getting Started
**Impact: CRITICAL**
Project setup, connection strings, initial configuration, and first steps with Supabase.
*No rules defined yet. See rules/_template.md for creating new rules.*
## 2. Auth
**Impact: CRITICAL**
Authentication, authorization, Row Level Security, social login, and session management.
*No rules defined yet. See rules/_template.md for creating new rules.*
## 3. Database
**Impact: CRITICAL**
Postgres database, migrations, queries, RLS policies, and data modeling.
*No rules defined yet. See rules/_template.md for creating new rules.*
## 4. Storage
**Impact: HIGH**
File uploads, buckets, access control, and media handling.
*No rules defined yet. See rules/_template.md for creating new rules.*
## 5. Edge Functions
**Impact: HIGH**
Serverless functions, Deno runtime, webhooks, and background tasks.
*No rules defined yet. See rules/_template.md for creating new rules.*
## 6. Realtime
**Impact: MEDIUM-HIGH**
Real-time subscriptions, presence, broadcast, and live updates.
*No rules defined yet. See rules/_template.md for creating new rules.*
## 7. Client Libraries
**Impact: MEDIUM**
supabase-js SDK, client configuration, and framework integrations.
*No rules defined yet. See rules/_template.md for creating new rules.*
## 8. CLI & Tools
**Impact: LOW-MEDIUM**
Supabase CLI, local development, migrations, CI/CD, and MCP integration.
*No rules defined yet. See rules/_template.md for creating new rules.*
## References
- https://supabase.com/docs
- https://supabase.com/docs/guides/getting-started
- https://supabase.com/docs/guides/auth
- https://supabase.com/docs/guides/database
- https://supabase.com/docs/guides/storage
- https://supabase.com/docs/guides/functions
- https://supabase.com/docs/guides/realtime

238
skills/supabase/PRODUCT_TEMPLATE.md Normal file
View File

@@ -0,0 +1,238 @@
# Product Team Contribution Guide
This document provides step-by-step instructions for adding your product's content to the Supabase Agent Skills.
## Structure Overview
This skill follows the [Agent Skills Open Standard](https://agentskills.io/specification):
```
skills/supabase/
├── SKILL.md # Entry point (update when adding sections)
├── AGENTS.md # [GENERATED] Do not edit directly
└── references/
├── _sections.md # Section definitions
├── _template.md # Reference template
├── _contributing.md # Writing guidelines
└── {prefix}-{name}.md # Your reference files
```
---
## Step 1: Setup Your Branch
```bash
git checkout main
git pull origin main
git checkout -b feature/supabase-skill-{your-product}
```
---
## Step 2: Identify Your Section
Check `references/_sections.md` for your product's section and prefix:
| Product | Section | Prefix |
| ---------------- | ------- | ----------- |
| Getting Started | 1 | `setup` |
| Auth | 2 | `auth` |
| Database | 3 | `database` |
| Storage | 4 | `storage` |
| Edge Functions | 5 | `functions` |
| Realtime | 6 | `realtime` |
| Client Libraries | 7 | `client` |
| CLI & Tools | 8 | `cli` |
---
## Step 3: Create Your Reference Files
Copy the template and create reference files:
```bash
cp references/_template.md references/{prefix}-{topic}.md
```
**Example file names:**
- `auth-nextjs-setup.md` - Next.js authentication setup
- `auth-rls-policies.md` - Row Level Security patterns
- `storage-upload-files.md` - File upload guide
- `functions-deploy.md` - Edge Functions deployment
---
## Step 4: Fill In the Template
Each reference file must have:
### Required Frontmatter
```yaml
---
title: Set Up Authentication with Next.js
impact: HIGH
impactDescription: Enables secure user authentication in 5 minutes
tags: auth, nextjs, setup, authentication
---
```
### Required Content
```markdown
## Set Up Authentication with Next.js
Brief explanation of what this guide covers and why it matters.
**Incorrect (describe the problem):**
\`\`\`typescript
// Bad pattern with explanation
\`\`\`
**Correct (describe the solution):**
\`\`\`typescript
// Good pattern with explanation
\`\`\`
Reference: [Supabase Auth Docs](https://supabase.com/docs/guides/auth)
```
---
## Step 5: Content Guidelines
### DO:
- Use concrete TypeScript/JavaScript examples
- Show **Incorrect** vs **Correct** patterns
- Include error messages developers might encounter
- Keep examples under 30 lines each
- Add comments explaining _why_, not _what_
### DON'T:
- Duplicate official documentation verbatim
- Include time-sensitive content (versions, dates)
- Assume prior Supabase knowledge
- Use placeholder names like `foo`, `bar`, `data`
---
## Step 6: Validate and Build
```bash
# Validate your reference files
npm run validate -- supabase
# Build AGENTS.md
npm run build -- supabase
# Run formatting
npm run check
```
Fix any validation errors before proceeding.
---
## Step 7: Open Pull Request
```bash
git add skills/supabase/references/
git commit -m "feat(skill): add {your-product} references"
git push origin feature/supabase-skill-{your-product}
```
Open PR with:
- Summary of references added
- List of files created
- Any cross-references to other products
---
## Step 8: Review Process
1. Product team member reviews for technical accuracy
2. AI team reviews for skill format compliance
3. CI validates and builds
4. Merge to main
---
## Impact Level Guidelines
Choose the appropriate impact level:
| Level | Use For |
| ----------- | ------------------------------------------------------ |
| CRITICAL | Security issues, auth bypasses, data exposure |
| HIGH | Core setup, essential patterns, breaking changes |
| MEDIUM-HIGH | Common mistakes, integration gotchas |
| MEDIUM | Best practices, optimization tips |
| LOW-MEDIUM | Configuration options, tooling tips |
| LOW | Advanced patterns, edge cases |
---
## Example Reference
Here's a complete example reference file:
```markdown
---
title: Configure Supabase Client for Next.js App Router
impact: HIGH
impactDescription: Enables type-safe Supabase access in Server and Client Components
tags: nextjs, app-router, client, setup
---
## Configure Supabase Client for Next.js App Router
Next.js App Router requires separate client configurations for Server Components and Client Components due to different execution environments.
**Incorrect (single client for both environments):**
\`\`\`typescript
// lib/supabase.ts
import { createClient } from "@supabase/supabase-js";
// This client won't work correctly in Server Components
export const supabase = createClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);
\`\`\`
**Correct (separate clients for server and browser):**
\`\`\`typescript
// lib/supabase/server.ts
import { createServerClient } from "@supabase/ssr";
import { cookies } from "next/headers";
export async function createClient() {
const cookieStore = await cookies();
return createServerClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!,
{ cookies: { getAll: () => cookieStore.getAll() } }
);
}
// lib/supabase/client.ts
import { createBrowserClient } from "@supabase/ssr";
export function createClient() {
return createBrowserClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);
}
\`\`\`
Reference: [Supabase SSR Docs](https://supabase.com/docs/guides/auth/server-side/nextjs)
```

116
skills/supabase/README.md Normal file
View File

@@ -0,0 +1,116 @@
# Supabase - Contributor Guide
This skill contains Supabase development guides optimized for AI agents and LLMs. It follows the [Agent Skills Open Standard](https://agentskills.io/specification).
## Quick Start for Contributors
```bash
# From repository root
npm install
# Validate existing references
npm run validate -- supabase
# Build AGENTS.md
npm run build -- supabase
```
## Creating a New Reference
1. **Choose a section prefix** based on the category (see `references/_sections.md`)
2. **Copy the template**:
```bash
cp references/_template.md references/{prefix}-your-reference-name.md
```
3. **Fill in the content** following the template structure
4. **Validate and build**:
```bash
npm run validate -- supabase
npm run build -- supabase
```
5. **Review** the generated `AGENTS.md`
## Repository Structure
```
skills/supabase/
├── SKILL.md # Agent-facing skill manifest (required)
├── AGENTS.md # [GENERATED] Compiled references document
├── README.md # This file
└── references/
├── _template.md # Reference template
├── _sections.md # Section definitions
├── _contributing.md # Writing guidelines
└── {prefix}-*.md # Individual references
```
## Reference File Structure
See `references/_template.md` for the complete template. Key elements:
```markdown
---
title: Clear, Action-Oriented Title
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: Specific benefit (e.g., "Prevents credential exposure")
tags: relevant, keywords
---
## [Title]
[1-2 sentence explanation]
**Incorrect (description):**
\`\`\`typescript
// What not to do
\`\`\`
**Correct (description):**
\`\`\`typescript
// What to do instead
\`\`\`
Reference: [Link](url)
```
## Section Prefixes
| Section | Prefix | Examples |
| ---------------- | ----------- | ------------------------------------- |
| Getting Started | `setup` | `setup-project.md`, `setup-env.md` |
| Auth | `auth` | `auth-nextjs.md`, `auth-rls.md` |
| Database | `database` | `database-migrations.md` |
| Storage | `storage` | `storage-upload.md` |
| Edge Functions | `functions` | `functions-deploy.md` |
| Realtime | `realtime` | `realtime-subscribe.md` |
| Client Libraries | `client` | `client-setup.md` |
| CLI & Tools | `cli` | `cli-local-dev.md` |
## Writing Guidelines
See `references/_contributing.md` for detailed guidelines. Key principles:
1. **Show concrete patterns** - "Use X instead of Y", not abstract advice
2. **Error-first structure** - Show the problem before the solution
3. **Quantify impact** - Include specific benefits
4. **Self-contained examples** - Complete, runnable code
5. **Semantic naming** - Use meaningful variable names
## Impact Levels
| Level | Use When |
| ----------- | ------------------------------------------------------ |
| CRITICAL | Security vulnerabilities, auth bypasses, data leaks |
| HIGH | Core functionality, performance issues, best practices |
| MEDIUM-HIGH | Integration patterns, common mistakes |
| MEDIUM | Optimization, alternative approaches |
| LOW-MEDIUM | Configuration tweaks, tooling setup |
| LOW | Advanced patterns, edge cases |

71
skills/supabase/SKILL.md Normal file
View File

@@ -0,0 +1,71 @@
---
name: supabase
description: Guides and best practices for working with Supabase. Covers getting started, Auth, Database, Storage, Edge Functions, Realtime, supabase-js SDK, CLI, and MCP integration. Use for any Supabase-related questions.
license: MIT
metadata:
author: supabase
version: "1.0.0"
organization: Supabase
date: January 2026
abstract: Comprehensive Supabase development guide for building applications with Supabase services. Contains guides across 8 categories covering Auth, Database, Storage, Edge Functions, Realtime, client libraries, CLI, and tooling. Each reference includes setup instructions, code examples, common mistakes, and integration patterns.
---
# Using Supabase
Comprehensive development guide for building applications with Supabase, maintained by Supabase. Contains guides across 8 categories to help developers integrate Supabase services effectively.
## When to Apply
Reference these guidelines when:
- Building applications with Supabase
- Integrating Supabase services (Auth, Database, Storage, etc.)
- Setting up local development with Supabase CLI
- Troubleshooting Supabase-related issues
- Configuring Supabase for production deployments
- Using the supabase-js SDK
## Guide Categories by Priority
| Priority | Category | Impact | Prefix |
| -------- | ---------------- | ----------- | ----------- |
| 1 | Getting Started | CRITICAL | `setup` |
| 2 | Auth | CRITICAL | `auth` |
| 3 | Database | CRITICAL | `database` |
| 4 | Storage | HIGH | `storage` |
| 5 | Edge Functions | HIGH | `functions` |
| 6 | Realtime | MEDIUM-HIGH | `realtime` |
| 7 | Client Libraries | MEDIUM | `client` |
| 8 | CLI & Tools | LOW-MEDIUM | `cli` |
## How to Use
Read individual reference files for detailed explanations and code examples:
```
references/setup-project.md
references/auth-nextjs.md
references/_sections.md
```
Each reference file contains:
- Brief explanation of the topic
- Setup instructions and code examples
- Common mistakes with wrong/correct patterns
- Integration patterns with other Supabase services
- Links to official documentation
## Full Compiled Document
For the complete guide with all references expanded: `AGENTS.md`
## References
- https://supabase.com/docs
- https://supabase.com/docs/guides/getting-started
- https://supabase.com/docs/guides/auth
- https://supabase.com/docs/guides/database
- https://supabase.com/docs/guides/storage
- https://supabase.com/docs/guides/functions
- https://supabase.com/docs/guides/realtime

0
skills/using-supabase/references/.gitkeep → skills/supabase/references/.gitkeep
View File

151
skills/supabase/references/_contributing.md Normal file
View File

@@ -0,0 +1,151 @@
# Writing Guidelines for Supabase References
This document provides guidelines for creating effective Supabase development
guides that work well with AI agents and LLMs.
## Key Principles
### 1. Concrete Examples Over Abstract Advice
Show exact code patterns. Avoid philosophical guidance.
**Good:** "Use `createClient()` with environment variables"
**Bad:** "Configure your client properly"
### 2. Error-First Structure
Always show the problematic pattern first, then the solution. This trains agents
to recognize anti-patterns.
```markdown
**Incorrect (hardcoded credentials):** [bad example]
**Correct (environment variables):** [good example]
```
### 3. Quantified Impact
Include specific benefits. Helps agents prioritize recommendations.
**Good:** "Reduces bundle size by 40%", "Prevents credential exposure"
**Bad:** "Better", "More secure", "Recommended"
### 4. Self-Contained Examples
Examples should be complete and runnable. Include imports and setup when needed.
```typescript
// Include imports for clarity
import { createClient } from "@supabase/supabase-js";
// Show complete setup
const supabase = createClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);
```
### 5. Semantic Naming
Use meaningful variable/function names. Names carry intent for LLMs.
**Good:** `supabase`, `authClient`, `userProfile`, `bucketName`
**Bad:** `client1`, `data`, `result`, `x`
---
## Code Example Standards
### TypeScript Formatting
```typescript
// Use clear formatting and proper typing
const { data, error } = await supabase
.from("users")
.select("id, email, created_at")
.eq("is_active", true);
// Not cramped
const { data, error } = await supabase.from("users").select("*").eq("is_active", true);
```
### Comments
- Explain _why_, not _what_
- Highlight security implications
- Point out common pitfalls
### Language Tags
- `typescript` - TypeScript/JavaScript code (preferred)
- `javascript` - Plain JavaScript when TS isn't appropriate
- `sql` - Database queries, RLS policies
- `bash` - CLI commands, environment setup
---
## Framework-Specific Guides
When creating guides for specific frameworks, include:
1. **Installation command** - `npm install @supabase/supabase-js`
2. **Environment variables** - Required `.env` configuration
3. **Client setup** - Framework-specific initialization
4. **Common mistakes** - Framework-specific pitfalls
### Supported Frameworks
Prefix reference files appropriately:
- `auth-nextjs.md` - Next.js App Router
- `auth-react.md` - React SPA
- `auth-remix.md` - Remix
- `client-nuxt.md` - Nuxt/Vue
---
## Impact Level Guidelines
| Level | Use When |
| --------------- | ----------------------------------------------------- |
| **CRITICAL** | Security vulnerabilities, auth bypasses, data leaks |
| **HIGH** | Core functionality, performance issues, best practices|
| **MEDIUM-HIGH** | Integration patterns, common mistakes |
| **MEDIUM** | Optimization, alternative approaches |
| **LOW-MEDIUM** | Configuration tweaks, tooling setup |
| **LOW** | Advanced patterns, edge cases |
---
## Reference Standards
**Primary Sources:**
- Supabase documentation (https://supabase.com/docs)
- Supabase GitHub examples
- Framework-specific documentation
**Format:**
```markdown
Reference: [Supabase Auth Docs](https://supabase.com/docs/guides/auth)
```
---
## Review Checklist
Before submitting a reference:
- [ ] Title is clear and action-oriented
- [ ] Impact level matches the importance
- [ ] impactDescription includes specific benefit
- [ ] Explanation is concise (1-2 sentences)
- [ ] Has at least 1 **Incorrect** code example
- [ ] Has at least 1 **Correct** code example
- [ ] Code uses semantic naming
- [ ] Comments explain _why_, not _what_
- [ ] Trade-offs mentioned if applicable
- [ ] Reference links included
- [ ] `npm run validate` passes
- [ ] `npm run build` generates correct output

37
skills/supabase/references/_sections.md Normal file
View File

@@ -0,0 +1,37 @@
# Section Definitions
This file defines the reference categories for Supabase development guides. References are automatically assigned to sections based on their filename prefix.
---
## 1. Getting Started (setup)
**Impact:** CRITICAL
**Description:** Project setup, connection strings, initial configuration, and first steps with Supabase.
## 2. Auth (auth)
**Impact:** CRITICAL
**Description:** Authentication, authorization, Row Level Security, social login, and session management.
## 3. Database (database)
**Impact:** CRITICAL
**Description:** Postgres database, migrations, queries, RLS policies, and data modeling.
## 4. Storage (storage)
**Impact:** HIGH
**Description:** File uploads, buckets, access control, and media handling.
## 5. Edge Functions (functions)
**Impact:** HIGH
**Description:** Serverless functions, Deno runtime, webhooks, and background tasks.
## 6. Realtime (realtime)
**Impact:** MEDIUM-HIGH
**Description:** Real-time subscriptions, presence, broadcast, and live updates.
## 7. Client Libraries (client)
**Impact:** MEDIUM
**Description:** supabase-js SDK, client configuration, and framework integrations.
## 8. CLI & Tools (cli)
**Impact:** LOW-MEDIUM
**Description:** Supabase CLI, local development, migrations, CI/CD, and MCP integration.

33
skills/supabase/references/_template.md Normal file
View File

@@ -0,0 +1,33 @@
---
title: Clear, Action-Oriented Title (e.g., "Set Up Authentication with Next.js")
impact: MEDIUM
impactDescription: Enables secure user authentication in minutes
tags: auth, nextjs, setup
---
## [Reference Title]
[1-2 sentence explanation of what this guide covers and why it matters.]
**Incorrect (describe the problem):**
```typescript
// Comment explaining what makes this problematic
const supabase = createClient("https://xxx.supabase.co", "hardcoded-key");
// Hardcoded credentials are a security risk
```
**Correct (describe the solution):**
```typescript
// Comment explaining why this is better
const supabase = createClient(
process.env.NEXT_PUBLIC_SUPABASE_URL!,
process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
);
// Environment variables keep credentials secure
```
[Optional: Additional context, setup steps, or configuration details]
Reference: [Supabase Docs](https://supabase.com/docs)

53
skills/using-supabase/AGENTS.md
View File

@@ -1,53 +0,0 @@
# Using Supabase
**Version 1.0.0**
Supabase
January 2026
> This document is optimized for AI agents and LLMs. Rules are prioritized by performance impact.
---
## Abstract
Comprehensive Supabase development guide covering Auth, Storage, Edge Functions, Realtime, CLI, supabase-js SDK, and MCP integration.
---
## Table of Contents
1. [TODO Section](#todo-section) - **TODO**
1. [Authentication](#authentication) - **CRITICAL**
2. [Database](#database) - **HIGH**
---
## 1. TODO Section
**Impact: TODO**
TODO - Define your sections based on Supabase product areas or patterns.
*No rules defined yet. See rules/_template.md for creating new rules.*
## 1. Authentication
**Impact: CRITICAL**
Authentication patterns, session management, and user identity.
*No rules defined yet. See rules/_template.md for creating new rules.*
## 2. Database
**Impact: HIGH**
Database queries, schema design, and data access patterns.
*No rules defined yet. See rules/_template.md for creating new rules.*
## References
- https://supabase.com/docs

147
skills/using-supabase/PRODUCT_TEMPLATE.md
View File

@@ -1,147 +0,0 @@
# Product Team Contribution Guide
This document provides step-by-step instructions for adding your product's content to the Supabase Agent Skills.
---
## Step 1: Setup Your Branch
```bash
git checkout feature/supabase-skill
git pull origin feature/supabase-skill
git checkout -b feature/supabase-skill-{your-product}
```
---
## Step 2: Create Your Hub File
Create a hub file at `skills/using-supabase/references/supabase-{your-product}.md`:
```markdown
# Supabase {Your Product} Guide
Brief description of what this product does and when to use it.
## Quick Start
Basic setup/usage example.
## Core Concepts
Key concepts developers need to understand.
## Common Patterns
Link to sub-resources for detailed patterns:
- [Pattern 1](./supabase-{your-product}/pattern-1.md)
- [Pattern 2](./supabase-{your-product}/pattern-2.md)
## Common Mistakes
What to avoid and why.
## Related Resources
Links to other Supabase products that integrate with this one.
```
---
## Step 3: Create Sub-Resources (Optional)
For detailed patterns, create a subdirectory:
```
skills/using-supabase/references/
├── supabase-{your-product}.md # Hub file
└── supabase-{your-product}/ # Sub-resources
├── pattern-1.md
├── pattern-2.md
└── common-mistakes.md
```
---
## Step 4: Content Guidelines
**DO:**
- Use concrete code examples (TypeScript/JavaScript)
- Show incorrect patterns with explanations
- Include error messages developers might see
- Link to related Supabase products
- Keep files focused (one concept per file)
**DON'T:**
- Duplicate official documentation verbatim
- Include overly long examples (keep under 50 lines)
- Assume prior Supabase knowledge
- Include time-sensitive content (versions, dates)
---
## Step 5: Reference File Format
Each reference file should follow this structure:
```markdown
# Title
One-paragraph description of this pattern/concept.
## When to Use
Describe the use case.
## Example
**Setup:**
\`\`\`typescript
// Setup code
\`\`\`
**Usage:**
\`\`\`typescript
// Usage example
\`\`\`
## Common Mistakes
**Incorrect:**
\`\`\`typescript
// What not to do
\`\`\`
**Correct:**
\`\`\`typescript
// What to do instead
\`\`\`
## Related
- [Related Resource 1](./path-to-resource.md)
- [Official Docs](https://supabase.com/docs/...)
```
---
## Step 6: Open Pull Request
```bash
git add skills/using-supabase/references/
git commit -m "feat(skill): add {your-product} references"
git push origin feature/supabase-skill-{your-product}
```
Open PR targeting `feature/supabase-skill` with:
- Summary of content added
- List of files created
- Any cross-references to other products
---
## Step 7: Review Process
1. Product team member reviews for technical accuracy
2. AI team reviews for skill format compliance
3. Merge to `feature/supabase-skill`

106
skills/using-supabase/README.md
View File

@@ -1,106 +0,0 @@
# Using Supabase - Contributor Guide
This repository contains Supabase development patterns and best practices optimized for AI agents and LLMs.
## Quick Start
```bash
# From repository root
npm install
# Validate existing rules
npm run validate
# Build AGENTS.md
npm run build
```
## Creating a New Rule
1. **Choose a section prefix** based on the category (see `rules/_sections.md`)
2. **Copy the template**:
```bash
cp rules/_template.md rules/{prefix}-your-rule-name.md
```
3. **Fill in the content** following the template structure
4. **Validate and build**:
```bash
npm run validate
npm run build
```
5. **Review** the generated `AGENTS.md`
## Repository Structure
```
skills/using-supabase/
├── SKILL.md # Agent-facing skill manifest
├── AGENTS.md # [GENERATED] Compiled rules document
├── README.md # This file
├── metadata.json # Version and metadata
├── PRODUCT_TEMPLATE.md # Template for product teams
├── references/ # Reference documentation
└── rules/
├── _template.md # Rule template
├── _sections.md # Section definitions
├── _contributing.md # Writing guidelines
└── *.md # Individual rules
```
## Rule File Structure
See `rules/_template.md` for the complete template. Key elements:
````markdown
---
title: Clear, Action-Oriented Title
impact: CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW
impactDescription: Quantified benefit (e.g., "10-100x faster")
tags: relevant, keywords
---
## [Title]
[1-2 sentence explanation]
**Incorrect (description):**
```typescript
// Comment explaining what's wrong
[Bad code example]
```
````
**Correct (description):**
```typescript
// Comment explaining why this is better
[Good code example]
```
```
## Writing Guidelines
See `rules/_contributing.md` for detailed guidelines. Key principles:
1. **Show concrete transformations** - "Change X to Y", not abstract advice
2. **Error-first structure** - Show the problem before the solution
3. **Quantify impact** - Include specific metrics
4. **Self-contained examples** - Complete, runnable code
5. **Semantic naming** - Use meaningful names
## Impact Levels
| Level | Improvement | Examples |
|-------|-------------|----------|
| CRITICAL | 10-100x or prevents failure | Security vulnerabilities, data loss |
| HIGH | 5-20x | Architecture decisions, core functionality |
| MEDIUM-HIGH | 2-5x | Design patterns, common anti-patterns |
| MEDIUM | 1.5-3x | Optimization, best practices |
| LOW-MEDIUM | 1.2-2x | Configuration, tooling |
| LOW | Incremental | Advanced techniques, edge cases |
```

47
skills/using-supabase/SKILL.md
View File

@@ -1,47 +0,0 @@
---
name: using-supabase
description: Comprehensive Supabase development guide. Use this skill when building applications with Supabase services, integrating Supabase APIs, or following Supabase best practices.
license: MIT
metadata:
author: supabase
version: "1.0.0"
---
# Using Supabase
Comprehensive development guide for building applications with Supabase, maintained by Supabase. Contains rules and patterns for using Supabase services effectively, prioritized by impact.
## When to Apply
Reference these guidelines when:
- Building applications with Supabase
- Integrating Supabase services into existing projects
- Following Supabase best practices
- Troubleshooting Supabase-related issues
- Configuring Supabase for production deployments
## Rule Categories by Priority
| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | TODO | TODO | `todo-` |
## How to Use
Read individual rule files for detailed explanations and code examples:
```
rules/todo-example.md
rules/_sections.md
```
Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Additional context and references
- Supabase-specific notes
## Full Compiled Document
For the complete guide with all rules expanded: `AGENTS.md`

7
skills/using-supabase/metadata.json
View File

@@ -1,7 +0,0 @@
{
"version": "1.0.0",
"organization": "Supabase",
"date": "January 2026",
"abstract": "Comprehensive Supabase development guide covering Auth, Storage, Edge Functions, Realtime, CLI, supabase-js SDK, and MCP integration.",
"references": ["https://supabase.com/docs"]
}

123
skills/using-supabase/rules/_contributing.md
View File

@@ -1,123 +0,0 @@
# Writing Guidelines for Supabase Rules
This document provides guidelines for creating effective Supabase best practice rules that work well with AI agents and LLMs.
## Key Principles
### 1. Concrete Transformation Patterns
Show exact code rewrites. Avoid philosophical advice.
**Good:** "Use `supabase.auth.getUser()` instead of `supabase.auth.getSession()` for server-side auth"
**Bad:** "Handle authentication properly"
### 2. Error-First Structure
Always show the problematic pattern first, then the solution. This trains agents to recognize anti-patterns.
```markdown
**Incorrect (client-side only):** [bad example]
**Correct (server-side validation):** [good example]
```
### 3. Quantified Impact
Include specific metrics when possible. Helps agents prioritize fixes.
**Good:** "Prevents unauthorized access", "Reduces latency by 50%", "Eliminates race conditions"
**Bad:** "Better", "More secure", "Faster"
### 4. Self-Contained Examples
Examples should be complete and runnable. Include imports and setup when needed.
```typescript
import { createClient } from "@supabase/supabase-js";
const supabase = createClient(url, key);
// Now show the pattern
const { data, error } = await supabase.from("users").select("*");
```
### 5. Semantic Naming
Use meaningful variable and table names. Names carry intent for LLMs.
**Good:** `users`, `posts`, `session`, `authUser`
**Bad:** `table1`, `data1`, `result`, `x`
---
## Code Example Standards
### TypeScript/JavaScript Formatting
```typescript
// Use clear formatting and meaningful names
const { data: users, error } = await supabase
.from("users")
.select("id, email, created_at")
.eq("is_active", true);
```
### Comments
- Explain _why_, not _what_
- Highlight security implications
- Point out common pitfalls
### Language Tags
- `typescript` - TypeScript/JavaScript code
- `sql` - SQL queries
- `bash` - CLI commands
---
## Impact Level Guidelines
| Level | Improvement | Use When |
|-------|-------------|----------|
| **CRITICAL** | 10-100x or prevents failure | Security vulnerabilities, data exposure, breaking changes |
| **HIGH** | 5-20x | Architecture decisions, core functionality |
| **MEDIUM-HIGH** | 2-5x | Common anti-patterns, reliability issues |
| **MEDIUM** | 1.5-3x | Optimization, best practices |
| **LOW-MEDIUM** | 1.2-2x | Configuration, tooling |
| **LOW** | Incremental | Advanced patterns, edge cases |
---
## Reference Standards
**Primary Sources:**
- Official Supabase documentation
- Supabase GitHub examples
- Supabase blog posts
**Format:**
```markdown
Reference: [Supabase Auth Docs](https://supabase.com/docs/guides/auth)
```
---
## Review Checklist
Before submitting a rule:
- [ ] Title is clear and action-oriented
- [ ] Impact level matches the severity
- [ ] impactDescription includes quantification
- [ ] Explanation is concise (1-2 sentences)
- [ ] Has at least 1 **Incorrect** code example
- [ ] Has at least 1 **Correct** code example
- [ ] Code uses semantic naming
- [ ] Comments explain _why_, not _what_
- [ ] Trade-offs mentioned if applicable
- [ ] Reference links included
- [ ] `npm run validate` passes
- [ ] `npm run build` generates correct output

23
skills/using-supabase/rules/_sections.md
View File

@@ -1,23 +0,0 @@
# Section Definitions
This file defines the rule categories for using Supabase. Rules are automatically assigned to sections based on their filename prefix.
---
## 1. TODO Section (todo)
**Impact:** TODO
**Description:** TODO - Define your sections based on Supabase product areas or patterns.
<!--
Example section format:
## 1. Authentication (auth)
**Impact:** CRITICAL
**Description:** Authentication patterns, session management, and user identity.
## 2. Database (db)
**Impact:** HIGH
**Description:** Database queries, schema design, and data access patterns.
Add sections as needed for each product area or cross-cutting concern.
-->

28
skills/using-supabase/rules/_template.md
View File

@@ -1,28 +0,0 @@
---
title: Clear, Action-Oriented Title (e.g., "Use Server-Side Auth for Protected Routes")
impact: MEDIUM
impactDescription: Brief quantified benefit
tags: relevant, keywords
---
## [Rule Title]
[1-2 sentence explanation of the problem and why it matters. Focus on impact.]
**Incorrect (describe the problem):**
```typescript
// Comment explaining what makes this problematic
// Bad code example
```
**Correct (describe the solution):**
```typescript
// Comment explaining why this is better
// Good code example
```
[Optional: Additional context, edge cases, or trade-offs]
Reference: [Supabase Docs](https://supabase.com/docs)