class-ai-agent 1.3.0 → 1.4.0

package/.claude/skills/supabase-postgres-best-practices/references/schema-primary-keys.md

@@ -0,0 +1,61 @@
+---
+title: Select Optimal Primary Key Strategy
+impact: HIGH
+impactDescription: Better index locality, reduced fragmentation
+tags: primary-key, identity, uuid, serial, schema
+---
+
+## Select Optimal Primary Key Strategy
+
+Primary key choice affects insert performance, index size, and replication
+efficiency.
+
+**Incorrect (problematic PK choices):**
+
+```sql
+-- identity is the SQL-standard approach
+create table users (
+  id serial primary key  -- Works, but IDENTITY is recommended
+);
+
+-- Random UUIDs (v4) cause index fragmentation
+create table orders (
+  id uuid default gen_random_uuid() primary key  -- UUIDv4 = random = scattered inserts
+);
+```
+
+**Correct (optimal PK strategies):**
+
+```sql
+-- Use IDENTITY for sequential IDs (SQL-standard, best for most cases)
+create table users (
+  id bigint generated always as identity primary key
+);
+
+-- For distributed systems needing UUIDs, use UUIDv7 (time-ordered)
+-- Requires pg_uuidv7 extension: create extension pg_uuidv7;
+create table orders (
+  id uuid default uuid_generate_v7() primary key  -- Time-ordered, no fragmentation
+);
+
+-- Alternative: time-prefixed IDs for sortable, distributed IDs (no extension needed)
+create table events (
+  id text default concat(
+    to_char(now() at time zone 'utc', 'YYYYMMDDHH24MISSMS'),
+    gen_random_uuid()::text
+  ) primary key
+);
+```
+
+Guidelines:
+
+- Single database: `bigint identity` (sequential, 8 bytes, SQL-standard)
+- Distributed/exposed IDs: UUIDv7 (requires pg_uuidv7) or ULID (time-ordered, no
+  fragmentation)
+- `serial` works but `identity` is SQL-standard and preferred for new
+  applications
+- Avoid random UUIDs (v4) as primary keys on large tables (causes index
+  fragmentation)
+
+Reference:
+[Identity Columns](https://www.postgresql.org/docs/current/sql-createtable.html#SQL-CREATETABLE-PARMS-GENERATED-IDENTITY)

package/.claude/skills/supabase-postgres-best-practices/references/security-privileges.md

@@ -0,0 +1,54 @@
+---
+title: Apply Principle of Least Privilege
+impact: MEDIUM
+impactDescription: Reduced attack surface, better audit trail
+tags: privileges, security, roles, permissions
+---
+
+## Apply Principle of Least Privilege
+
+Grant only the minimum permissions required. Never use superuser for application queries.
+
+**Incorrect (overly broad permissions):**
+
+```sql
+-- Application uses superuser connection
+-- Or grants ALL to application role
+grant all privileges on all tables in schema public to app_user;
+grant all privileges on all sequences in schema public to app_user;
+
+-- Any SQL injection becomes catastrophic
+-- drop table users; cascades to everything
+```
+
+**Correct (minimal, specific grants):**
+
+```sql
+-- Create role with no default privileges
+create role app_readonly nologin;
+
+-- Grant only SELECT on specific tables
+grant usage on schema public to app_readonly;
+grant select on public.products, public.categories to app_readonly;
+
+-- Create role for writes with limited scope
+create role app_writer nologin;
+grant usage on schema public to app_writer;
+grant select, insert, update on public.orders to app_writer;
+grant usage on sequence orders_id_seq to app_writer;
+-- No DELETE permission
+
+-- Login role inherits from these
+create role app_user login password 'xxx';
+grant app_writer to app_user;
+```
+
+Revoke public defaults:
+
+```sql
+-- Revoke default public access
+revoke all on schema public from public;
+revoke all on all tables in schema public from public;
+```
+
+Reference: [Roles and Privileges](https://supabase.com/blog/postgres-roles-and-privileges)

package/.claude/skills/supabase-postgres-best-practices/references/security-rls-basics.md

@@ -0,0 +1,50 @@
+---
+title: Enable Row Level Security for Multi-Tenant Data
+impact: CRITICAL
+impactDescription: Database-enforced tenant isolation, prevent data leaks
+tags: rls, row-level-security, multi-tenant, security
+---
+
+## Enable Row Level Security for Multi-Tenant Data
+
+Row Level Security (RLS) enforces data access at the database level, ensuring users only see their own data.
+
+**Incorrect (application-level filtering only):**
+
+```sql
+-- Relying only on application to filter
+select * from orders where user_id = $current_user_id;
+
+-- Bug or bypass means all data is exposed!
+select * from orders;  -- Returns ALL orders
+```
+
+**Correct (database-enforced RLS):**
+
+```sql
+-- Enable RLS on the table
+alter table orders enable row level security;
+
+-- Create policy for users to see only their orders
+create policy orders_user_policy on orders
+  for all
+  using (user_id = current_setting('app.current_user_id')::bigint);
+
+-- Force RLS even for table owners
+alter table orders force row level security;
+
+-- Set user context and query
+set app.current_user_id = '123';
+select * from orders;  -- Only returns orders for user 123
+```
+
+Policy for authenticated role:
+
+```sql
+create policy orders_user_policy on orders
+  for all
+  to authenticated
+  using (user_id = auth.uid());
+```
+
+Reference: [Row Level Security](https://supabase.com/docs/guides/database/postgres/row-level-security)

package/.claude/skills/supabase-postgres-best-practices/references/security-rls-performance.md

@@ -0,0 +1,63 @@
+---
+title: Optimize RLS Policies for Performance
+impact: HIGH
+impactDescription: 5-10x faster RLS queries with proper patterns
+tags: rls, performance, security, optimization
+---
+
+## Optimize RLS Policies for Performance
+
+Poorly written RLS policies can cause severe performance issues. Use subqueries and indexes strategically.
+
+**Incorrect (function called for every row):**
+
+```sql
+create policy orders_policy on orders
+  using (auth.uid() = user_id);  -- auth.uid() called per row!
+
+-- With 1M rows, auth.uid() is called 1M times
+```
+
+**Correct (wrap functions in SELECT):**
+
+```sql
+create policy orders_policy on orders
+  using ((select auth.uid()) = user_id);  -- Called once, cached
+
+-- 100x+ faster on large tables
+```
+
+Use security definer functions for complex checks:
+
+`SECURITY DEFINER` functions run with the creator's privileges and bypass RLS on any tables they touch — which is what makes them useful for internal lookups, but also what makes them dangerous if misused. Always include an explicit `auth.uid()` check inside the function body, keep them in a non-exposed schema, and revoke `EXECUTE` from any role that shouldn't call them directly.
+
+```sql
+-- Create helper function in a private schema
+create or replace function private.is_team_member(team_id bigint)
+returns boolean
+language sql
+security definer
+set search_path = ''
+as $$
+  select exists (
+    select 1 from public.team_members
+    -- always check the calling user's identity inside the function
+    where team_id = $1 and user_id = (select auth.uid())
+  );
+$$;
+
+-- Revoke direct execution from public roles
+revoke execute on function private.is_team_member(bigint) from PUBLIC, anon, authenticated, service_role;
+
+-- Use in policy (indexed lookup, not per-row check)
+create policy team_orders_policy on orders
+  using ((select private.is_team_member(team_id)));
+```
+
+Always add indexes on columns used in RLS policies:
+
+```sql
+create index orders_user_id_idx on orders (user_id);
+```
+
+Reference: [RLS Performance](https://supabase.com/docs/guides/database/postgres/row-level-security#rls-performance-recommendations)

package/.cursor/CURSOR.md

@@ -104,6 +104,8 @@ Reusable playbooks: **`.cursor/skills/*/SKILL.md`** (and related `.md` files whe
 | `deploy` | Deployment pipeline |
 | `security-review` | Security audit |
 | `agent-continuity` | Cross-tool session handoff via `.agent/SESSION.md` |
+| `supabase` | Supabase products, Auth, CLI, MCP, migrations, RLS |
+| `supabase-postgres-best-practices` | Postgres performance, indexes, RLS tuning |
 
 ---
 
@@ -119,6 +121,7 @@ Reusable playbooks: **`.cursor/skills/*/SKILL.md`** (and related `.md` files whe
 | `accessibility-checklist.md` | WCAG-oriented checks |
 | `codegraph.md` | CodeGraph install and Claude Code setup |
 | `agent-continuity.md` | Session handoff and `/resume` / `/handoff` |
+| `supabase.md` | Supabase skills, MCP OAuth, secrets |
 
 ---
 

package/.cursor/mcp.json

@@ -10,6 +10,10 @@
         "--path",
         "${workspaceFolder}"
       ]
+    },
+    "supabase": {
+      "type": "http",
+      "url": "https://mcp.supabase.com/mcp?features=docs"
     }
   }
 }

package/.cursor/references/supabase.md

@@ -0,0 +1,55 @@
+# Supabase reference
+
+[class-ai-agent](https://github.com/khoantd/class-ai-agent) bundles official [Supabase Agent Skills](https://github.com/supabase/agent-skills) and wires the **Supabase MCP** server for Cursor and Kiro.
+
+## Skills
+
+| Skill | Use when |
+|-------|----------|
+| `supabase` | Any Supabase product work: Database, Auth, Edge Functions, Realtime, Storage, CLI, MCP, migrations, RLS, `supabase-js`, `@supabase/ssr` |
+| `supabase-postgres-best-practices` | SQL, schema design, indexes, pooling, RLS performance, query review |
+
+Paths: `.cursor/skills/supabase/`, `.cursor/skills/supabase-postgres-best-practices/` (and `.claude/skills/`, `.kiro/skills/` after install).
+
+Invoke with **`@`** mention or let the agent load them when the task matches. See each skill’s `SKILL.md` for security checklists and workflow.
+
+**Maintainers:** refresh vendored copies with `npm run sync:supabase-skills` (pin in `scripts/supabase-skills.lock.json`).
+
+## MCP (Cursor & Kiro)
+
+| Tool | MCP config |
+|------|------------|
+| Cursor | `.cursor/mcp.json` → `mcpServers.supabase` |
+| Kiro | `.kiro/settings/mcp.json` → `mcpServers.supabase` |
+
+Server URL: `https://mcp.supabase.com/mcp?features=docs` (HTTP, OAuth 2.1).
+
+### After install
+
+1. **Reload** Cursor or **restart** Kiro so MCP servers connect.
+2. On first use, complete **OAuth** in the browser when prompted (Supabase account).
+3. Health check (expect `401` without a token — server is up):
+   ```bash
+   curl -so /dev/null -w "%{http_code}" "https://mcp.supabase.com/mcp"
+   ```
+
+Useful MCP tools include `search_docs`, `list_projects`, `list_tables`, `execute_sql`, `get_advisors`, `get_logs`, and migration helpers. Prefer `search_docs` over guessing API behavior.
+
+**Note:** Upstream skill text may refer to a project-root `.mcp.json`. In this scaffold, Supabase MCP lives only under `.cursor/mcp.json` and `.kiro/settings/mcp.json` — do not add a duplicate root `.mcp.json`.
+
+## Claude Code
+
+Skills install to `.claude/skills/`. Claude Code does not get MCP from this package by default. Options:
+
+- [Supabase MCP setup](https://supabase.com/docs/guides/getting-started/mcp)
+- [Supabase plugin for Claude Code](https://github.com/supabase/agent-skills)
+
+## Secrets
+
+Never commit service role keys, secret keys, or project tokens. Use environment variables per `.cursor/rules/security.mdc` (and `.claude/rules/security.md`, `.kiro/steering/security.md`).
+
+## Learn more
+
+- [Supabase AI skills docs](https://supabase.com/docs/guides/ai-tools/ai-skills)
+- [Upstream repository](https://github.com/supabase/agent-skills)
+- [THIRD_PARTY_NOTICES.md](../../THIRD_PARTY_NOTICES.md) — license and pinned version

package/.cursor/rules/tech-stack.mdc

@@ -23,8 +23,9 @@ globs: "**/*.{ts,tsx,js,jsx,mjs,cjs,json,md,prisma,yml,yaml}"
 | **Backend Framework** | Express.js + Node | Fastify | Hapi, Koa |
 | **API Style** | REST (default) | tRPC (fullstack TS) | GraphQL (unless needed) |
 | **Language** | TypeScript (always) | — | Plain JavaScript |
-| **Database** | PostgreSQL | — | MySQL (prefer PG) |
+| **Database** | PostgreSQL | Supabase (managed Postgres + bundled `supabase` skills) | MySQL (prefer PG) |
 | **ORM** | Prisma | Drizzle | Sequelize, TypeORM |
+| **BaaS (Auth, DB, Storage, Realtime)** | — | Supabase | Firebase |
 | **Cache** | Redis (ioredis) | Upstash Redis | Memcached |
 | **Queue — Simple jobs** | BullMQ (Redis-backed) | — | — |
 | **Queue — Enterprise/Microservices** | RabbitMQ | Kafka (high-throughput streams) | — |

package/.cursor/settings.json

@@ -4,5 +4,10 @@
   "skills_dir": ".cursor/skills",
   "agents_dir": ".cursor/agents",
   "references_dir": ".cursor/references",
-  "note": "Parallels .claude/settings.json. Cursor loads .cursor/rules/*.mdc automatically; other paths are for @ mentions and docs."
+  "note": "Parallels .claude/settings.json. Cursor loads .cursor/rules/*.mdc automatically; other paths are for @ mentions and docs.",
+  "plugins": {
+    "supabase": {
+      "enabled": true
+    }
+  }
 }

package/.cursor/skills/supabase/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: supabase
+description: "Use when doing ANY task involving Supabase. Triggers: Supabase products (Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues); client libraries and SSR integrations (supabase-js, @supabase/ssr) in Next.js, React, SvelteKit, Astro, Remix; auth issues (login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, RLS); Supabase CLI or MCP server; schema changes, migrations, security audits, Postgres extensions (pg_graphql, pg_cron, pg_vector)."
+metadata:
+  author: supabase
+  version: "0.1.2"
+---
+
+# Supabase
+
+## Core Principles
+
+**1. Supabase changes frequently — verify against changelog and current docs before implementing.**
+Do not rely on training data for Supabase features. Function signatures, config.toml settings, and API conventions change between versions.
+
+First, fetch `https://supabase.com/changelog.md` (a lightweight summary index — not a heavy pull), scan for `breaking-change` tags relevant to your task, and follow the linked page for any that apply. Then look up the relevant topic using the documentation access methods below.
+
+**2. Verify your work.**
+After implementing any fix, run a test query to confirm the change works. A fix without verification is incomplete.
+
+**3. Recover from errors, don't loop.**
+If an approach fails after 2-3 attempts, stop and reconsider. Try a different method, check documentation, inspect the error more carefully, and review relevant logs when available. Supabase issues are not always solved by retrying the same command, and the answer is not always in the logs, but logs are often worth checking before proceeding.
+
+**4. Exposing tables to the Data API:** Depending on the user's [Data API settings](https://supabase.com/dashboard/project/<ref>/integrations/data_api/settings), newly created tables may not be automatically exposed via the Data (REST) API. If this is the case, `anon` and `authenticated` roles will need to be explicitly granted access.
+
+> Note that this is separate from RLS, which controls which _rows_ are visible once a table is accessible, not whether the table is accessible at all.
+
+When a user reports a SQL-created table is unexpectedly inaccessible, check their Data API settings and whether the roles have been granted access via explicit `GRANT` SQL. When granting public (`anon`/`authenticated`) access, always enable RLS too. See [Exposing a Table to the Data API](https://supabase.com/docs/guides/api/securing-your-api.md) for the full setup workflow.
+
+**5. RLS in exposed schemas.**
+Enable RLS on every table in any exposed schema, which includes `public` by default. This is critical in Supabase because tables in exposed schemas can be reachable through the Data API when the `anon`/`authenticated` roles have access (see [Exposing a Table to the Data API](https://supabase.com/docs/guides/api/securing-your-api.md)). For private schemas, prefer RLS as defense in depth. After enabling RLS, create policies that match the actual access model rather than defaulting every table to the same `auth.uid()` pattern.
+
+**6. Security checklist.**
+When working on any Supabase task that touches auth, RLS, views, storage, or user data, run through this checklist. These are Supabase-specific security traps that silently create vulnerabilities:
+
+- **Auth and session security**
+  - **Never use `user_metadata` claims in JWT-based authorization decisions.** In Supabase, `raw_user_meta_data` is user-editable and can appear in `auth.jwt()`, so it is unsafe for RLS policies or any other authorization logic. Store authorization data in `raw_app_meta_data` / `app_metadata` instead.
+  - **Deleting a user does not invalidate existing access tokens.** Sign out or revoke sessions first, keep JWT expiry short for sensitive apps, and for strict guarantees validate `session_id` against `auth.sessions` on sensitive operations.
+  - **If you use `app_metadata` or `auth.jwt()` for authorization, remember JWT claims are not always fresh until the user's token is refreshed.**
+
+- **API key and client exposure**
+  - **Never expose the `service_role` or secret key in public clients.** Prefer publishable keys for frontend code. Legacy `anon` keys are only for compatibility. In Next.js, any `NEXT_PUBLIC_` env var is sent to the browser.
+
+- **RLS, views, and privileged database code**
+  - **Views bypass RLS by default.** In Postgres 15 and above, use `CREATE VIEW ... WITH (security_invoker = true)`. In older versions of Postgres, protect your views by revoking access from the `anon` and `authenticated` roles, or by putting them in an unexposed schema.
+  - **UPDATE requires a SELECT policy.** In Postgres RLS, an UPDATE needs to first SELECT the row. Without a SELECT policy, updates silently return 0 rows — no error, just no change.
+  - **`auth.role()` is deprecated — use the `TO` clause instead.** Supabase has deprecated `auth.role()` in favour of specifying the target role directly on the policy with `TO authenticated` or `TO anon`. Beyond deprecation, `auth.role() = 'authenticated'` breaks silently when anonymous sign-ins are enabled, because anonymous users carry the `authenticated` Postgres role and pass the check regardless of whether the user is genuinely signed in.
+    ```sql
+    -- Deprecated (do not use)
+    create policy "example" on table_name for select
+    using ( auth.role() = 'authenticated' );
+    ```
+  - **`TO authenticated` alone is authentication without authorization (BOLA / IDOR).** Using `TO authenticated` only checks the role — it does not restrict which rows a user can access. The correct pattern combines `TO authenticated` with an ownership predicate in `USING`:
+    ```sql
+    create policy "example" on table_name for select
+    to authenticated
+    using ( (select auth.uid()) = user_id );
+    ```
+  - **UPDATE policies require both `USING` and `WITH CHECK`.** Without `WITH CHECK`, a user can reassign a row's `user_id` to another user:
+    ```sql
+    create policy "example" on table_name for update
+    to authenticated
+    using ( (select auth.uid()) = user_id )
+    with check ( (select auth.uid()) = user_id );
+    ```
+  - **`SECURITY DEFINER` functions bypass RLS.** A `SECURITY DEFINER` function runs with its creator's privileges — typically a role with `bypassrls` (e.g., `postgres`). Never add `SECURITY DEFINER` to resolve a permission error; it silently removes access control without fixing the underlying cause. Prefer `SECURITY INVOKER`.
+  - **`SECURITY DEFINER` functions in `public` are callable by all roles.** Postgres grants `EXECUTE` to `PUBLIC` by default for every new function, so any `SECURITY DEFINER` function in `public` is a public API endpoint callable by `anon` and `authenticated` (which inherit from `PUBLIC`) without any additional grant. When `SECURITY DEFINER` is genuinely needed (e.g., bypassing RLS on an internal lookup table), keep the function in a non-exposed schema, always include an `auth.uid()` check in the function body, and run `supabase db advisors` after making changes.
+
+- **Storage access control**
+  - **Storage upsert requires INSERT + SELECT + UPDATE.** Granting only INSERT allows new uploads but file replacement (upsert) silently fails. You need all three.
+
+- **Dependency and supply-chain security**
+  - **Always pin package versions and commit lockfiles** when installing Supabase packages (`supabase-js`, `@supabase/ssr`, `supabase-py`, etc.). See the [npm security guide](https://supabase.com/docs/guides/security/npm-security.md) for the full checklist.
+
+For any security concern not covered above, fetch the Supabase product security index: `https://supabase.com/docs/guides/security/product-security.md`
+
+## Supabase CLI
+
+Always discover commands via `--help` — never guess. The CLI structure changes between versions.
+
+```bash
+supabase --help                    # All top-level commands
+supabase <group> --help            # Subcommands (e.g., supabase db --help)
+supabase <group> <command> --help  # Flags for a specific command
+```
+
+**Supabase CLI Known gotchas:**
+
+- `supabase db query` requires **CLI v2.79.0+** → use MCP `execute_sql` or `psql` as fallback
+- `supabase db advisors` requires **CLI v2.81.3+** → use MCP `get_advisors` as fallback
+- When you need a new migration SQL file, **always** create it with `supabase migration new <name>` first. Never invent a migration filename or rely on memory for the expected format.
+
+**Version check and upgrade:** Run `supabase --version` to check. For CLI changelogs and version-specific features, consult the [CLI documentation](https://supabase.com/docs/reference/cli/introduction) or [GitHub releases](https://github.com/supabase/cli/releases).
+
+## Supabase MCP Server
+
+For setup instructions, server URL, and configuration, see the [MCP setup guide](https://supabase.com/docs/guides/getting-started/mcp).
+
+**Troubleshooting connection issues** — follow these steps in order:
+
+1. **Check if the server is reachable:**
+   `curl -so /dev/null -w "%{http_code}" https://mcp.supabase.com/mcp`
+   A `401` is expected (no token) and means the server is up. Timeout or "connection refused" means it may be down.
+
+2. **Check `.mcp.json` configuration:**
+   Verify the project root has a valid `.mcp.json` with the correct server URL. If missing, create one pointing to `https://mcp.supabase.com/mcp`.
+
+3. **Authenticate the MCP server:**
+   If the server is reachable and `.mcp.json` is correct but tools aren't visible, the user needs to authenticate. The Supabase MCP server uses OAuth 2.1 — tell the user to trigger the auth flow in their agent, complete it in the browser, and reload the session.
+
+## Supabase Documentation
+
+Before implementing any Supabase feature, find the relevant documentation. Use these methods in priority order:
+
+1. **MCP `search_docs` tool** (preferred — returns relevant snippets directly)
+2. **Fetch docs pages as markdown** — any docs page can be fetched by appending `.md` to the URL path.
+3. **Web search** for Supabase-specific topics when you don't know which page to look at.
+
+## Making and Committing Schema Changes
+
+**To make schema changes, use `execute_sql` (MCP) or `supabase db query` (CLI).** These run SQL directly on the database without creating migration history entries, so you can iterate freely and generate a clean migration when ready.
+
+Do NOT use `apply_migration` to change a local database schema — it writes a migration history entry on every call, which means you can't iterate, and `supabase db diff` / `supabase db pull` will produce empty or conflicting diffs. If you use it, you'll be stuck with whatever SQL you passed on the first try.
+
+**When ready to commit** your changes to a migration file:
+
+1. **Run advisors** → `supabase db advisors` (CLI v2.81.3+) or MCP `get_advisors`. Fix any issues.
+2. **Review the Security Checklist above** if your changes involve views, functions, triggers, or storage.
+3. **Generate the migration** → `supabase db pull <descriptive-name> --local --yes`
+4. **Verify** → `supabase migration list --local`
+
+## Reference Guides
+
+- **Skill Feedback** → [references/skill-feedback.md](references/skill-feedback.md)
+  **MUST read when** the user reports that this skill gave incorrect guidance or is missing information.

package/.cursor/skills/supabase/UPSTREAM.md

@@ -0,0 +1,16 @@
+# Upstream
+
+| Field | Value |
+|-------|-------|
+| Repository | [supabase/agent-skills](https://github.com/supabase/agent-skills) |
+| Ref | `v0.1.5` |
+| Commit | `30e4d716faf4b459291d607783fe866a70d0f4e9` |
+| License | MIT |
+
+Vendored by [class-ai-agent](https://github.com/khoantd/class-ai-agent). Refresh:
+
+```bash
+npm run sync:supabase-skills
+```
+
+Copyright (c) Supabase — see [upstream LICENSE](https://github.com/supabase/agent-skills/blob/v0.1.5/LICENSE).

package/.cursor/skills/supabase/assets/feedback-issue-template.md

@@ -0,0 +1,17 @@
+## What happened
+
+**Task:** <!-- e.g., "Set up MFA on patient records" -->
+
+**Skill said:** <!-- e.g., "Use auth.jwt()->'app_metadata' in the RLS policy" -->
+
+**Expected:** <!-- e.g., "The function also needs SECURITY DEFINER + grant to supabase_auth_admin" -->
+
+## Source
+
+**File:** <!-- e.g., references/security-model.md -->
+
+**Section:** <!-- e.g., "Trust Boundaries > user_metadata vs app_metadata" -->
+
+## Fix suggestion
+
+<!-- Leave blank if unsure -->

package/.cursor/skills/supabase/references/skill-feedback.md

@@ -0,0 +1,17 @@
+# Skill Feedback
+
+Use this when the user reports that the skill gave incorrect guidance, is missing information, or could be improved. This is about the skill (agent instructions), not about Supabase the product.
+
+## Steps
+
+1. **Ask permission** — Ask the user if they'd like to submit feedback to the skill maintainers. If they decline, move on.
+
+2. **Draft the issue** — Use the template at [assets/feedback-issue-template.md](../assets/feedback-issue-template.md) to structure the feedback. Fill in the fields based on the conversation. Always identify which specific reference file and section caused the problem.
+
+3. **Submit** — Create a GitHub Issue on the `supabase/agent-skills` repository using the draft as the issue body. The title must follow this format: `user-feedback: <summary of the problem>`.
+
+4. **Share the result** — Share the issue URL with the user after submission. If submission fails, give the user this link to create the issue manually:
+
+```
+https://github.com/supabase/agent-skills/issues/new
+```

package/.cursor/skills/supabase-postgres-best-practices/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: supabase-postgres-best-practices
+description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
+license: MIT
+metadata:
+  author: supabase
+  version: "1.1.1"
+  organization: Supabase
+  date: January 2026
+  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.
+---
+
+# Supabase Postgres Best Practices
+
+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.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing SQL queries or designing schemas
+- Implementing indexes or query optimization
+- Reviewing database performance issues
+- Configuring connection pooling or scaling
+- Optimizing for Postgres-specific features
+- Working with Row-Level Security (RLS)
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Query Performance | CRITICAL | `query-` |
+| 2 | Connection Management | CRITICAL | `conn-` |
+| 3 | Security & RLS | CRITICAL | `security-` |
+| 4 | Schema Design | HIGH | `schema-` |
+| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
+| 6 | Data Access Patterns | MEDIUM | `data-` |
+| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
+| 8 | Advanced Features | LOW | `advanced-` |
+
+## How to Use
+
+Read individual rule files for detailed explanations and SQL examples:
+
+```
+references/query-missing-indexes.md
+references/query-partial-indexes.md
+references/_sections.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect SQL example with explanation
+- Correct SQL example with explanation
+- Optional EXPLAIN output or metrics
+- Additional context and references
+- Supabase-specific notes (when applicable)
+
+## References
+
+- https://www.postgresql.org/docs/current/
+- https://supabase.com/docs
+- https://wiki.postgresql.org/wiki/Performance_Optimization
+- https://supabase.com/docs/guides/database/overview
+- https://supabase.com/docs/guides/auth/row-level-security

package/.cursor/skills/supabase-postgres-best-practices/UPSTREAM.md

@@ -0,0 +1,16 @@
+# Upstream
+
+| Field | Value |
+|-------|-------|
+| Repository | [supabase/agent-skills](https://github.com/supabase/agent-skills) |
+| Ref | `v0.1.5` |
+| Commit | `30e4d716faf4b459291d607783fe866a70d0f4e9` |
+| License | MIT |
+
+Vendored by [class-ai-agent](https://github.com/khoantd/class-ai-agent). Refresh:
+
+```bash
+npm run sync:supabase-skills
+```
+
+Copyright (c) Supabase — see [upstream LICENSE](https://github.com/supabase/agent-skills/blob/v0.1.5/LICENSE).