refactor: flatten realtime references to flat structure

- Merge feature/supabase-skill
- Move realtime/* files to realtime-* prefix in references/
- Remove .claude from git tracking
- Update SKILL.md with flat paths
- Rebuild AGENTS.md

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

.claude-plugin/marketplace.json

@@ -14,7 +14,7 @@
 			"description": "Postgres performance optimization and best practices. Use when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.",
 			"source": "./",
 			"strict": false,
-			"skills": ["./skills/postgres-best-practices"]
+			"skills": ["./skills/supabase-postgres-best-practices"]
 		}
 	]
 }

.gitignore

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

packages/skills-build/src/build.ts

@@ -29,9 +29,9 @@ function generateSectionMap(sections: Section[]): Record<string, number> {
 }
 
 /**
- * Recursively get all markdown files from a directory
+ * Get all markdown files from a directory (flat, no subdirectories)
  */
-function getMarkdownFilesRecursive(dir: string): string[] {
+function getMarkdownFiles(dir: string): string[] {
 	const files: string[] = [];
 
 	if (!existsSync(dir)) {
@@ -49,10 +49,8 @@ function getMarkdownFilesRecursive(dir: string): string[] {
 		const fullPath = join(dir, entry);
 		const stat = statSync(fullPath);
 
-		if (stat.isDirectory()) {
+		// Only include files, skip directories
-			// Recursively scan subdirectories
+		if (stat.isFile() && entry.endsWith(".md")) {
-			files.push(...getMarkdownFilesRecursive(fullPath));
-		} else if (entry.endsWith(".md")) {
 			files.push(fullPath);
 		}
 	}
@@ -60,6 +58,13 @@ function getMarkdownFilesRecursive(dir: string): string[] {
 	return files;
 }
 
+/**
+ * @deprecated Use getMarkdownFiles instead - nested directories are not supported
+ */
+function getMarkdownFilesRecursive(dir: string): string[] {
+	return getMarkdownFiles(dir);
+}
+
 /**
  * Parse section definitions from _sections.md (legacy function for validation)
  */
@@ -171,36 +176,20 @@ function parseSectionsFromFile(filePath: string): Section[] {
 }
 
 /**
- * Parse all _sections.md files from references directory and subdirectories
+ * Parse _sections.md from references directory root only
+ * Note: Nested directories are not supported - all reference files should be in references/ root
  */
 function parseAllSections(referencesDir: string): Section[] {
-	const allSections: Section[] = [];
+	const sectionsFile = join(referencesDir, "_sections.md");
-
+	if (existsSync(sectionsFile)) {
-	// Parse root _sections.md
+		return parseSectionsFromFile(sectionsFile);
-	const rootSectionsFile = join(referencesDir, "_sections.md");
-	if (existsSync(rootSectionsFile)) {
-		allSections.push(...parseSectionsFromFile(rootSectionsFile));
 	}
-
+	return [];
-	// Scan subdirectories for _sections.md files
-	if (existsSync(referencesDir)) {
-		const entries = readdirSync(referencesDir);
-		for (const entry of entries) {
-			const fullPath = join(referencesDir, entry);
-			if (statSync(fullPath).isDirectory()) {
-				const subSectionsFile = join(fullPath, "_sections.md");
-				if (existsSync(subSectionsFile)) {
-					allSections.push(...parseSectionsFromFile(subSectionsFile));
-				}
-			}
-		}
-	}
-
-	return allSections;
 }
 
 /**
- * Get all reference files (excluding _sections.md)
+ * Get all reference files from references/ root (excluding _sections.md)
+ * Note: Nested directories are not supported - all reference files should be in references/ root
  */
 function getReferenceFiles(referencesDir: string): string[] {
 	const files: string[] = [];
@@ -220,15 +209,8 @@ function getReferenceFiles(referencesDir: string): string[] {
 		const fullPath = join(referencesDir, entry);
 		const stat = statSync(fullPath);
 
-		if (stat.isDirectory()) {
+		// Only include files at root level, skip directories
-			// Recursively scan subdirectories
+		if (stat.isFile() && entry.endsWith(".md")) {
-			const subEntries = readdirSync(fullPath);
-			for (const subEntry of subEntries) {
-				if (!subEntry.startsWith("_") && subEntry.endsWith(".md")) {
-					files.push(join(fullPath, subEntry));
-				}
-			}
-		} else if (entry.endsWith(".md")) {
 			files.push(fullPath);
 		}
 	}
@@ -418,7 +400,8 @@ if (isMainModule) {
 export {
 	buildSkill,
 	generateSectionMap,
-	getMarkdownFilesRecursive,
+	getMarkdownFiles,
+	getMarkdownFilesRecursive, // deprecated, use getMarkdownFiles
 	getReferenceFiles,
 	parseAllSections,
 	parseSections,

packages/skills-build/src/validate.ts

@@ -2,7 +2,7 @@ import { existsSync } from "node:fs";
 import { basename } from "node:path";
 import {
 	generateSectionMap,
-	getMarkdownFilesRecursive,
+	getMarkdownFiles,
 	parseAllSections,
 	parseSections,
 } from "./build.js";
@@ -158,8 +158,8 @@ function validateSkill(paths: SkillPaths): boolean {
 	const sections = parseAllSections(paths.referencesDir);
 	const sectionMap = generateSectionMap(sections);
 
-	// Get all markdown files recursively (excluding _ prefixed files)
+	// Get all markdown files from references/ root (excluding _ prefixed files)
-	const files = getMarkdownFilesRecursive(paths.referencesDir);
+	const files = getMarkdownFiles(paths.referencesDir);
 
 	if (files.length === 0) {
 		console.log(`  No rule files found.`);

skills/supabase/AGENTS.md

@@ -26,70 +26,52 @@ supabase/
 
 | Priority | Category | Impact | Prefix |
 |----------|----------|--------|--------|
-| 1 | Row Level Security | CRITICAL | `rls-` |
+| 1 | Getting Started | CRITICAL | `getting-` |
-| 1 | Channel Setup | HIGH | `setup-` |
+| 2 | Database | CRITICAL | `db-` |
-| 2 | Connection Pooling | CRITICAL | `conn-` |
+| 3 | Authentication | CRITICAL | `auth-` |
-| 2 | Broadcast Messaging | CRITICAL | `broadcast-` |
+| 4 | Storage | HIGH | `storage-` |
-| 3 | Schema Design | HIGH | `schema-` |
+| 5 | Edge Functions | HIGH | `edge-` |
-| 3 | Presence Tracking | MEDIUM | `presence-` |
+| 6 | Realtime | MEDIUM-HIGH | `realtime-` |
-| 4 | Migrations | HIGH | `migrations-` |
+| 7 | SDK | HIGH | `sdk-` |
-| 4 | Postgres Changes | MEDIUM | `postgres-` |
+| 8 | CLI | CRITICAL | `cli-` |
-| 5 | Performance | CRITICAL | `perf-` |
+| 9 | MCP | MEDIUM | `mcp-` |
-| 5 | Implementation Patterns | CRITICAL | `patterns-` |
+| 10 | Tooling | MEDIUM | `tooling-` |
-| 6 | Security | CRITICAL | `security-` |
+| 11 | Vectors | MEDIUM | `vectors-` |
 
 Reference files are named `{prefix}-{topic}.md` (e.g., `query-missing-indexes.md`).
 
 ## Available References
 
-**Connection Pooling** (`conn-`):
+**Database** (`db-`):
-- `references/db/conn-pooling.md`
+- `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`
 
-**Migrations** (`migrations-`):
+**Realtime** (`realtime-`):
-- `references/db/migrations-diff.md`
+- `references/realtime-broadcast-basics.md`
-- `references/db/migrations-idempotent.md`
+- `references/realtime-broadcast-database.md`
-- `references/db/migrations-testing.md`
+- `references/realtime-patterns-cleanup.md`
-
+- `references/realtime-patterns-debugging.md`
-**Performance** (`perf-`):
+- `references/realtime-patterns-errors.md`
-- `references/db/perf-indexes.md`
+- `references/realtime-postgres-changes.md`
-- `references/db/perf-query-optimization.md`
+- `references/realtime-presence-tracking.md`
-
+- `references/realtime-setup-auth.md`
-**Row Level Security** (`rls-`):
+- `references/realtime-setup-channels.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`
-
-**Schema Design** (`schema-`):
-- `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`
-
-**Security** (`security-`):
-- `references/db/security-functions.md`
-- `references/db/security-service-role.md`
-
-**Broadcast Messaging** (`broadcast-`):
-- `references/realtime/broadcast-basics.md`
-- `references/realtime/broadcast-database.md`
-
-**Implementation Patterns** (`patterns-`):
-- `references/realtime/patterns-cleanup.md`
-- `references/realtime/patterns-debugging.md`
-- `references/realtime/patterns-errors.md`
-
-**Postgres Changes** (`postgres-`):
-- `references/realtime/postgres-changes.md`
-
-**Presence Tracking** (`presence-`):
-- `references/realtime/presence-tracking.md`
-
-**Channel Setup** (`setup-`):
-- `references/realtime/setup-auth.md`
-- `references/realtime/setup-channels.md`
 
 ---
 

skills/supabase/SKILL.md

@@ -31,59 +31,25 @@ curl -H "Accept: text/markdown" https://supabase.com/docs/<path>
 
 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   |
-| 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 |
-| 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  |
-| Schema Design      | `references/db/schema-*.md`     | auth.users FKs, timestamps, JSONB, extensions  |
+| Migrations         | `references/db-migrations-*.md`  | CLI workflows, idempotent patterns, db diff    |
-| Migrations         | `references/db/migrations-*.md` | CLI workflows, idempotent patterns, db diff    |
+| Performance        | `references/db-perf-*.md`        | Indexes (BRIN, GIN), query optimization        |
-| Performance        | `references/db/perf-*.md`       | Indexes (BRIN, GIN), query optimization        |
+| Security           | `references/db-security-*.md`    | Service role key, security_definer functions   |
-| Security           | `references/db/security-*.md`   | Service role key, security_definer functions   |
-
-### 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        |
+| Channel Setup    | `references/realtime-setup-*.md`     | Creating channels, naming conventions, auth         |
-| Channel Setup    | `references/realtime/setup-*.md`    | Creating channels, naming conventions, auth         |
+| Broadcast        | `references/realtime-broadcast-*.md` | Client messaging, database-triggered broadcasts     |
-| Broadcast        | `references/realtime/broadcast-*.md`| Client messaging, database-triggered broadcasts     |
+| Presence         | `references/realtime-presence-*.md`  | User online status, shared state tracking           |
-| Presence         | `references/realtime/presence-*.md` | User online status, shared state tracking           |
+| Postgres Changes | `references/realtime-postgres-*.md`  | Database change listeners (prefer Broadcast)        |
-| Postgres Changes | `references/realtime/postgres-*.md` | Database change listeners (prefer Broadcast)        |
+| Patterns         | `references/realtime-patterns-*.md`  | Cleanup, error handling, React integration          |
-| Patterns         | `references/realtime/patterns-*.md` | Cleanup, error handling, React integration          |
 
-### Client Libraries & CLI
+**CLI Usage:** Always use `npx supabase` instead of `supabase` for version consistency across team members.
-
-| 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,45 @@
+# Reference Sections
+
+## 1. Getting Started (getting)
+**Impact:** CRITICAL
+**Description:** Local development setup and CLI workflow guides
+
+## 2. Database (db)
+**Impact:** CRITICAL
+**Description:** Database schema, RLS, migrations, and performance
+
+## 3. Authentication (auth)
+**Impact:** CRITICAL
+**Description:** Auth flows, sessions, OAuth, MFA, and SSO
+
+## 4. Storage (storage)
+**Impact:** HIGH
+**Description:** File uploads, access control, and CDN
+
+## 5. Edge Functions (edge)
+**Impact:** HIGH
+**Description:** Serverless functions, deployment, and patterns
+
+## 6. Realtime (realtime)
+**Impact:** MEDIUM-HIGH
+**Description:** Subscriptions, presence, and broadcast
+
+## 7. SDK (sdk)
+**Impact:** HIGH
+**Description:** Client libraries, queries, and TypeScript
+
+## 8. CLI (cli)
+**Impact:** CRITICAL
+**Description:** CLI commands, migrations, and local development
+
+## 9. MCP (mcp)
+**Impact:** MEDIUM
+**Description:** MCP server setup and configuration
+
+## 10. Tooling (tooling)
+**Impact:** MEDIUM
+**Description:** Tool selection and workflow guides
+
+## 11. Vectors (vectors)
+**Impact:** MEDIUM
+**Description:** pgvector, embeddings, and semantic search

skills/supabase/references/db/_sections.md

@@ -1,36 +0,0 @@
-# Section Definitions
-
-Reference files are grouped by prefix. Claude loads specific files based on user
-queries.
-
----
-
-## 1. Row Level Security (rls)
-
-**Impact:** CRITICAL
-**Description:** RLS policies, common mistakes, performance optimizations, and security patterns specific to Supabase's auth.uid() integration.
-
-## 2. Connection Pooling (conn)
-
-**Impact:** CRITICAL
-**Description:** Supabase-specific connection pooling with Supavisor. Transaction mode (port 6543) vs Session mode (port 5432).
-
-## 3. Schema Design (schema)
-
-**Impact:** HIGH
-**Description:** Supabase-specific schema patterns including auth.users foreign keys, timestamptz, JSONB usage, extensions, and Realtime.
-
-## 4. Migrations (migrations)
-
-**Impact:** HIGH
-**Description:** Migration workflows using Supabase CLI, idempotent patterns, supabase db diff, and local testing strategies.
-
-## 5. Performance (perf)
-
-**Impact:** CRITICAL
-**Description:** Index strategies (BRIN, GIN, partial), query optimization for PostgREST, and Supabase-specific performance patterns.
-
-## 6. Security (security)
-
-**Impact:** CRITICAL
-**Description:** Service role key handling, security definer functions in private schemas, and Supabase-specific security patterns.

skills/supabase/references/realtime/_sections.md

@@ -1,31 +0,0 @@
-# Section Definitions
-
-Reference files are grouped by prefix. Claude loads specific files based on user
-queries.
-
----
-
-## 1. Channel Setup (setup)
-
-**Impact:** HIGH
-**Description:** Channel creation, naming conventions, configuration options, and authentication setup for private channels.
-
-## 2. Broadcast Messaging (broadcast)
-
-**Impact:** CRITICAL
-**Description:** Sending and receiving real-time messages between clients, database-triggered broadcasts using `realtime.broadcast_changes()` and `realtime.send()`.
-
-## 3. Presence Tracking (presence)
-
-**Impact:** MEDIUM
-**Description:** Tracking user online status, shared state synchronization, and presence lifecycle management.
-
-## 4. Postgres Changes (postgres)
-
-**Impact:** MEDIUM
-**Description:** Database change listeners via logical replication. Note: Broadcast is recommended for use cases that require higher scalability.
-
-## 5. Implementation Patterns (patterns)
-
-**Impact:** CRITICAL
-**Description:** Channel cleanup, React integration patterns, error handling, and connection management best practices.