feat: supabase skill with db and realtime references

Adds the supabase agent skill with comprehensive references for:
- Database: schema design, RLS policies, migrations, indexing, query optimization, security
- Realtime: channels, broadcast, presence, postgres changes, auth setup, error handling

Author: Rodriguespn

.gitignore

@@ -12,7 +12,6 @@ dist/
 # AI Agent directories
 .agent/
 .agents/
-.claude/
 .codex/
 .gemini/
 .goose/
@@ -21,3 +20,4 @@ dist/
 
 # Generated skills in any dot directory
 .*/skills/
+.claude/

GETTING_STARTED.md

@@ -0,0 +1,69 @@
+# Getting Started
+
+Contributor guide for adding content to the Supabase Agent Skills.
+
+## Quick Start
+
+1. Create a reference file in `skills/supabase/references/`
+2. Use `skills/supabase/references/_template.md` as your starting point
+3. Update `skills/supabase/SKILL.md` to reference your new file
+4. Run `npm run build && npm run check`
+
+## Creating Reference Files
+
+```bash
+# Main topic
+skills/supabase/references/{feature}.md
+
+# Sub-topics (optional)
+skills/supabase/references/{feature}/{subtopic}.md
+```
+
+**Examples:**
+
+- `references/auth.md` - Authentication overview
+- `references/auth/nextjs.md` - Auth setup for Next.js
+- `references/storage.md` - Storage overview
+
+## Writing Guidelines
+
+Follow the [Agent Skills Open Standard](https://agentskills.io/) best practices:
+
+1. **Concise is key** - Only include what Claude doesn't already know
+2. **Show, don't tell** - Prefer code examples over explanations
+3. **Progressive disclosure** - Keep SKILL.md lean, put details in reference files
+4. **Concrete examples** - Include runnable code with real values
+5. **Common mistakes first** - Help agents avoid pitfalls
+
+**Good example** (~50 tokens):
+
+```typescript
+// Get user session
+const { data: { session } } = await supabase.auth.getSession();
+```
+
+**Avoid** (~150 tokens):
+
+```markdown
+Sessions are a way to track authenticated users. When a user logs in,
+a session is created. You can get the current session using the
+getSession method which returns a promise...
+```
+
+## Update SKILL.md
+
+Add your reference to the resources table:
+
+```markdown
+| Area         | Resource                | When to Use                    |
+| ------------ | ----------------------- | ------------------------------ |
+| Your Feature | `references/feature.md` | Brief description of use cases |
+```
+
+## Validate
+
+```bash
+npm run validate -- supabase   # Check files
+npm run build -- supabase      # Generate AGENTS.md
+npm run check                  # Format and lint
+```

skills/supabase/AGENTS.md

@@ -0,0 +1,69 @@
+# supabase
+
+> **Note:** `CLAUDE.md` is a symlink to this file.
+
+## Overview
+
+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.
+
+## Structure
+
+```
+supabase/
+  SKILL.md       # Main skill file - read this first
+  AGENTS.md      # This navigation guide
+  CLAUDE.md      # Symlink to AGENTS.md
+  references/    # Detailed reference files
+```
+
+## Usage
+
+1. Read `SKILL.md` for the main skill instructions
+2. Browse `references/` for detailed documentation on specific topics
+3. Reference files are loaded on-demand - read only what you need
+
+## Reference Categories
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Database | CRITICAL | `db-` |
+| 2 | Realtime | MEDIUM-HIGH | `realtime-` |
+
+Reference files are named `{prefix}-{topic}.md` (e.g., `query-missing-indexes.md`).
+
+## Available References
+
+**Database** (`db-`):
+- `references/db-conn-pooling.md`
+- `references/db-migrations-diff.md`
+- `references/db-migrations-idempotent.md`
+- `references/db-migrations-testing.md`
+- `references/db-perf-indexes.md`
+- `references/db-perf-query-optimization.md`
+- `references/db-rls-common-mistakes.md`
+- `references/db-rls-mandatory.md`
+- `references/db-rls-performance.md`
+- `references/db-rls-policy-types.md`
+- `references/db-rls-views.md`
+- `references/db-schema-auth-fk.md`
+- `references/db-schema-extensions.md`
+- `references/db-schema-jsonb.md`
+- `references/db-schema-realtime.md`
+- `references/db-schema-timestamps.md`
+- `references/db-security-functions.md`
+- `references/db-security-service-role.md`
+
+**Realtime** (`realtime-`):
+- `references/realtime-broadcast-basics.md`
+- `references/realtime-broadcast-database.md`
+- `references/realtime-patterns-cleanup.md`
+- `references/realtime-patterns-debugging.md`
+- `references/realtime-patterns-errors.md`
+- `references/realtime-postgres-changes.md`
+- `references/realtime-presence-tracking.md`
+- `references/realtime-setup-auth.md`
+- `references/realtime-setup-channels.md`
+
+---
+
+*27 reference files across 2 categories*

skills/supabase/CLAUDE.md

@@ -0,0 +1 @@
+AGENTS.md

skills/supabase/SKILL.md

@@ -0,0 +1,55 @@
+---
+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 covering Auth, Database, Storage, Edge Functions, Realtime, client libraries, CLI, and tooling. Each reference includes setup instructions, code examples, common mistakes, and integration patterns.
+---
+
+# Supabase
+
+Supabase is an open source Firebase alternative that provides a Postgres database, authentication, instant APIs, edge functions, realtime subscriptions, and storage. It's fully compatible with Postgres and works with any language, framework, or ORM.
+
+## Supabase Documentation
+
+Always reference the Supabase documentation before making Supabase-related claims. The documentation is the source of truth for all Supabase-related information.
+
+You can use the `curl` commands to fetch the documentation page as markdown:
+
+**Documentation:**
+
+```bash
+# Fetch any doc page as markdown
+curl -H "Accept: text/markdown" https://supabase.com/docs/<path>
+```
+
+## Overview of Resources
+
+Reference the appropriate resource file based on the user's needs:
+
+### Database
+
+| Area               | Resource                        | When to Use                                    |
+| ------------------ | ------------------------------- | ---------------------------------------------- |
+| RLS Security       | `references/db-rls-*.md`        | Row Level Security policies, common mistakes   |
+| Connection Pooling | `references/db-conn-pooling.md` | Transaction vs Session mode, port 6543 vs 5432 |
+| Schema Design      | `references/db-schema-*.md`     | auth.users FKs, timestamps, JSONB, extensions  |
+| Migrations         | `references/db-migrations-*.md` | CLI workflows, idempotent patterns, db diff    |
+| Performance        | `references/db-perf-*.md`       | Indexes (BRIN, GIN), query optimization        |
+| Security           | `references/db-security-*.md`   | Service role key, security_definer functions   |
+
+### Realtime
+
+| Area             | Resource                             | When to Use                                     |
+| ---------------- | ------------------------------------ | ----------------------------------------------- |
+| Channel Setup    | `references/realtime-setup-*.md`     | Creating channels, naming conventions, auth     |
+| Broadcast        | `references/realtime-broadcast-*.md` | Client messaging, database-triggered broadcasts |
+| Presence         | `references/realtime-presence-*.md`  | User online status, shared state tracking       |
+| Postgres Changes | `references/realtime-postgres-*.md`  | Database change listeners (prefer Broadcast)    |
+| Patterns         | `references/realtime-patterns-*.md`  | Cleanup, error handling, React integration      |
+
+**CLI Usage:** Always use `npx supabase` instead of `supabase` for version consistency across team members.

skills/supabase/references/_sections.md

@@ -0,0 +1,16 @@
+# Section Definitions
+
+Reference files are grouped by prefix. Claude loads specific files based on user
+queries.
+
+---
+
+## 1. Database (db)
+
+**Impact:** CRITICAL
+**Description:** Row Level Security policies, connection pooling, schema design patterns, migrations, performance optimization, and security functions for Supabase Postgres.
+
+## 2. Realtime (realtime)
+
+**Impact:** MEDIUM-HIGH
+**Description:** Channel setup, Broadcast messaging, Presence tracking, Postgres Changes listeners, cleanup patterns, error handling, and debugging.

skills/supabase/references/_template.md

@@ -0,0 +1,46 @@
+---
+title: Action-Oriented Title
+tags: relevant, keywords
+---
+
+# Feature Name
+
+One-sentence description of what this does and when to use it.
+
+## Quick Start
+
+```typescript
+// Minimal working example with real code
+import { createClient } from "@supabase/supabase-js";
+const supabase = createClient(url, key);
+
+// Core operation
+const { data, error } = await supabase.from("table").select("*");
+```
+
+## Common Patterns
+
+### Pattern Name
+
+```typescript
+// Concrete example - prefer this over explanations
+const { data } = await supabase.from("users").select("id, email").eq("active", true);
+```
+
+## Common Mistakes
+
+**Mistake**: Brief description of what goes wrong.
+
+```typescript
+// Incorrect
+const data = await supabase.from("users").select(); // Missing error handling
+
+// Correct
+const { data, error } = await supabase.from("users").select("*");
+if (error) throw error;
+```
+
+## Related
+
+- [subtopic.md](subtopic.md) - For advanced X patterns
+- [Docs](https://supabase.com/docs/guides/feature) - Official guide

skills/supabase/references/db-conn-pooling.md

@@ -0,0 +1,106 @@
+---
+title: Use Correct Connection Pooling Mode
+impact: CRITICAL
+impactDescription: Prevents connection exhaustion and enables 10-100x scalability
+tags: connection-pooling, supavisor, transaction-mode, session-mode
+---
+
+## Use Correct Connection Pooling Mode
+
+Supabase provides Supavisor for connection pooling. Choose the right mode based
+on your application type.
+
+## Transaction Mode (Port 6543)
+
+Best for: Serverless functions, edge computing, stateless APIs.
+
+```bash
+## Transaction mode connection string
+postgres://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:6543/postgres
+```
+
+**Limitations:**
+
+- No prepared statements
+- No SET commands
+- No LISTEN/NOTIFY
+- No temp tables
+
+```javascript
+// Prisma - disable prepared statements
+const prisma = new PrismaClient({
+  datasources: {
+    db: {
+      url: process.env.DATABASE_URL + "?pgbouncer=true",
+    },
+  },
+});
+```
+
+## Session Mode (Port 5432)
+
+Best for: Long-running servers, apps needing prepared statements.
+
+```bash
+## Session mode (via pooler for IPv4)
+postgres://postgres.[ref]:[password]@aws-0-[region].pooler.supabase.com:5432/postgres
+```
+
+## Direct Connection (Port 5432)
+
+Best for: Migrations, admin tasks, persistent servers.
+
+```bash
+## Direct connection (IPv6 only unless IPv4 add-on enabled)
+postgres://postgres.[ref]:[password]@db.[ref].supabase.co:5432/postgres
+```
+
+## Common Mistakes
+
+**Incorrect:**
+
+```javascript
+// Serverless with session mode - exhausts connections
+const pool = new Pool({
+  connectionString: "...pooler.supabase.com:5432/postgres",
+  max: 20, // Too many connections per instance!
+});
+```
+
+**Correct:**
+
+```javascript
+// Serverless with transaction mode
+const pool = new Pool({
+  connectionString: "...pooler.supabase.com:6543/postgres",
+  max: 1, // Single connection per serverless instance
+});
+```
+
+**Incorrect:**
+
+```bash
+## Transaction mode with prepared statements
+DATABASE_URL="...pooler.supabase.com:6543/postgres"
+## Error: prepared statement already exists
+```
+
+**Correct:**
+
+```bash
+## Add pgbouncer=true to disable prepared statements
+DATABASE_URL="...pooler.supabase.com:6543/postgres?pgbouncer=true"
+```
+
+## Connection Limits by Compute Size
+
+| Compute | Direct Connections | Pooler Clients |
+| ------- | ------------------ | -------------- |
+| Nano    | 60                 | 200            |
+| Small   | 90                 | 400            |
+| Medium  | 120                | 600            |
+| Large   | 160                | 800            |
+
+## Related
+
+- [Docs](https://supabase.com/docs/guides/database/connecting-to-postgres)