feature: vectors agent references

.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,80 @@
+# supabase
+
+> **Note:** `CLAUDE.md` is a symlink to this file.
+
+## Overview
+
+Guides and best practices for working with Supabase. Covers getting started, Auth, Database, Vectors/AI, Storage, Edge Functions, Realtime, supabase-js SDK, CLI, and MCP integration. Use for any Supabase-related questions including vector search, embeddings, RAG, and semantic search.
+
+## 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 | Vectors | MEDIUM | `vectors-` |
+| 3 | 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`
+
+**Vectors** (`vectors-`):
+- `references/vectors-embed-generation.md`
+- `references/vectors-index-hnsw.md`
+- `references/vectors-index-ivfflat.md`
+- `references/vectors-perf-tuning.md`
+- `references/vectors-rag-patterns.md`
+- `references/vectors-search-hybrid.md`
+- `references/vectors-search-semantic.md`
+- `references/vectors-setup-pgvector.md`
+
+---
+
+*35 reference files across 3 categories*

skills/supabase/CLAUDE.md

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

skills/supabase/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: supabase
+description: Guides and best practices for working with Supabase. Covers getting started, Auth, Database, Vectors/AI, Storage, Edge Functions, Realtime, supabase-js SDK, CLI, and MCP integration. Use for any Supabase-related questions including vector search, embeddings, RAG, and semantic search.
+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:
+
+### Core Guides
+
+| Area             | Resource                         | When to Use                                              |
+| ---------------- | -------------------------------- | -------------------------------------------------------- |
+| Getting Started  | `references/getting-started.md`  | Setting up a project, connection strings, dependencies   |
+| Referencing Docs | `references/referencing-docs.md` | Looking up official documentation, verifying information |
+
+### Authentication & Security
+
+| Area               | Resource             | When to Use                                |
+| ------------------ | -------------------- | ------------------------------------------ |
+| Auth Overview      | `references/auth.md` | Authentication, social login, sessions     |
+| Row Level Security | `references/rls.md`  | Database security policies, access control |
+
+### Database
+
+| Area               | Resource                        | When to Use                                    |
+| ------------------ | ------------------------------- | ---------------------------------------------- |
+| Database           | `references/database.md`        | Postgres queries, migrations, modeling         |
+| 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   |
+
+### Vectors & AI
+
+| Area               | Resource                          | When to Use                                     |
+| ------------------ | --------------------------------- | ----------------------------------------------- |
+| Vector Setup       | `references/vectors/setup-*.md`   | pgvector extension, vector columns, dimensions  |
+| Vector Indexing    | `references/vectors/index-*.md`   | HNSW, IVFFlat, index parameters, concurrent     |
+| Vector Search      | `references/vectors/search-*.md`  | Semantic search, hybrid search, match_documents |
+| Embeddings         | `references/vectors/embed-*.md`   | gte-small, OpenAI, triggers, Edge Functions     |
+| RAG                | `references/vectors/rag-*.md`     | Document ingestion, chunking, query pipelines   |
+| Vector Performance | `references/vectors/perf-*.md`    | Pre-warming, compute sizing, batch operations   |
+
+### Storage & Media
+
+| Area    | Resource                | When to Use                  |
+| ------- | ----------------------- | ---------------------------- |
+| Storage | `references/storage.md` | File uploads, buckets, media |
+
+### Edge Functions
+
+| Area           | Resource                       | When to Use                                  |
+| -------------- | ------------------------------ | -------------------------------------------- |
+| Edge Functions | `references/edge-functions.md` | Serverless functions, Deno runtime, webhooks |
+
+### Realtime
+
+| Area     | Resource                 | When to Use                                  |
+| -------- | ------------------------ | -------------------------------------------- |
+| Realtime | `references/realtime.md` | Real-time subscriptions, presence, broadcast |
+
+### Client Libraries & CLI
+
+| Area         | Resource                    | When to Use                              |
+| ------------ | --------------------------- | ---------------------------------------- |
+| supabase-js  | `references/supabase-js.md` | JavaScript/TypeScript SDK, client config |
+| Supabase CLI | `references/cli.md`         | Local development, migrations, CI/CD     |
+| MCP Server   | `references/mcp.md`         | AI agent integration, MCP tooling        |

skills/supabase/references/_sections.md

@@ -0,0 +1,21 @@
+# 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. Vectors (vectors)
+
+**Impact:** MEDIUM
+**Description:** pgvector setup, HNSW/IVFFlat indexing, semantic and hybrid search, embedding generation, RAG patterns, and performance tuning.
+
+## 3. 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