Skip to content

feature: development workflows references #39

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Rodriguespn merged 8 commits into from
Feb 16, 2026
Merged

feature: development workflows references #39

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
510d016
rebase and house keeping
Rodriguespn Feb 12, 2026
6a7bf02
wip: cli developement guides
Rodriguespn Feb 13, 2026
6853323
update agents.md
Rodriguespn Feb 13, 2026
0ef479f
fix developement workflows
Rodriguespn Feb 13, 2026
01fe1fc
fix: update SKILL.md, dev-mcp-setup, and rebuild AGENTS.md files
Rodriguespn Feb 13, 2026
e382fb6
fix: update SKILL.md, development references, and rebuild AGENTS.md
Rodriguespn Feb 16, 2026
19da04d
minor changes to mcp setup guide
Rodriguespn Feb 16, 2026
e44bc05
update agents.md
Rodriguespn Feb 16, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 46 additions & 7 deletions skills/supabase/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,14 +16,44 @@ supabase/
2. Browse `references/` for detailed documentation on specific topics
3. Reference files are loaded on-demand - read only what you need

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 provides several language sdks, including supabase-js and supabase-py.
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.

## Development Guidance

**Before performing any Supabase development task, read the development reference files.** They define which tools to use, how to interact with Supabase instances, and the correct workflows for local and remote development. Getting these wrong leads to schema drift, migration conflicts, and broken deployments.

- **Which tool to use for each operation** — read [references/dev-cli-vs-mcp.md](references/dev-cli-vs-mcp.md)
- **New project or first-time setup** — read [references/dev-getting-started.md](references/dev-getting-started.md)
- **Local development workflow** (CLI migrations, psql debugging, type generation) — read [references/dev-local-workflow.md](references/dev-local-workflow.md)
- **Remote project interaction** (MCP queries, logs, advisors, deploying) — read [references/dev-remote-workflow.md](references/dev-remote-workflow.md)
- **CLI command details and pitfalls** — read [references/dev-cli-reference.md](references/dev-cli-reference.md)
- **MCP server configuration** — read [references/dev-mcp-setup.md](references/dev-mcp-setup.md)
- **MCP tool usage** (execute_sql, apply_migration, get_logs, get_advisors) — read [references/dev-mcp-tools.md](references/dev-mcp-tools.md)

When the user's project has no `supabase/` directory, start with [references/dev-getting-started.md](references/dev-getting-started.md). When it already exists, pick up from the appropriate workflow (local or remote) based on user intentions.

## Overview of Resources

Reference the appropriate resource file based on the user's needs:
Reference the appropriate resource file based on the user's needs.

### Development (read first)

**Read these files before any Supabase development task.** They define the correct tools, workflows, and boundaries for interacting with Supabase instances. Start here when setting up a project, running CLI or MCP commands, writing migrations, connecting to a database, or deciding which tool to use for an operation.

| Area | Resource | When to Use |
| --------------- | ----------------------------------- | -------------------------------------------------------------- |
| Getting Started | `references/dev-getting-started.md` | New project setup, CLI install, first-time init |
| Local Workflow | `references/dev-local-workflow.md` | Local development with CLI migrations and psql debugging |
| Remote Workflow | `references/dev-remote-workflow.md` | Developing against hosted Supabase project using MCP |
| CLI vs MCP | `references/dev-cli-vs-mcp.md` | Tool roles: CLI (schema), psql/MCP (debugging), SDK (app code) |
| CLI Reference | `references/dev-cli-reference.md` | CLI command details, best practices, pitfalls |
| MCP Setup | `references/dev-mcp-setup.md` | Configuring Supabase remote MCP server for hosted projects |
| MCP Tools | `references/dev-mcp-tools.md` | execute_sql, apply_migration, get_logs, get_advisors |

### Authentication & Security

Read when implementing sign-up, sign-in, OAuth, SSO, MFA, passwordless flows, auth hooks, or server-side auth patterns.

| Area | Resource | When to Use |
| ------------------ | ----------------------------------- | -------------------------------------------------------- |
| Auth Core | `references/auth-core-*.md` | Sign-up, sign-in, sessions, password reset |
Expand All @@ -36,6 +66,8 @@ Reference the appropriate resource file based on the user's needs:

### Database

Read when designing tables, writing RLS policies, creating migrations, configuring connection pooling, or optimizing query performance.

| Area | Resource | When to Use |
| ------------------ | ------------------------------- | ---------------------------------------------- |
| RLS Security | `references/db-rls-*.md` | Row Level Security policies, common mistakes |
Expand All @@ -47,6 +79,8 @@ Reference the appropriate resource file based on the user's needs:

### Edge Functions

Read when creating, deploying, or debugging Deno-based Edge Functions — including authentication, database access, CORS, routing, streaming, and testing patterns.

| Area | Resource | When to Use |
| ---------------------- | ------------------------------------- | -------------------------------------- |
| Quick Start | `references/edge-fun-quickstart.md` | Creating and deploying first function |
Expand All @@ -67,6 +101,8 @@ Reference the appropriate resource file based on the user's needs:

### Realtime

Read when implementing live updates — Broadcast messaging, Presence tracking, or Postgres Changes listeners.

| Area | Resource | When to Use |
| ---------------- | ------------------------------------ | ----------------------------------------------- |
| Channel Setup | `references/realtime-setup-*.md` | Creating channels, naming conventions, auth |
Expand All @@ -77,6 +113,8 @@ Reference the appropriate resource file based on the user's needs:

### SDK (supabase-js)

Read when writing application code that interacts with Supabase — client setup, queries, error handling, TypeScript types, or framework integration.

| Area | Resource | When to Use |
| --------------- | ------------------------------- | ----------------------------------------- |
| Client Setup | `references/sdk-client-*.md` | Browser/server client, SSR, configuration |
Expand All @@ -88,6 +126,8 @@ Reference the appropriate resource file based on the user's needs:

### Storage

Read when implementing file uploads, downloads, image transformations, or configuring storage access control and CDN caching.

| Area | Resource | When to Use |
| --------------- | ------------------------------------- | ---------------------------------------------- |
| Access Control | `references/storage-access-control.md`| Bucket policies, RLS for storage |
Expand All @@ -98,13 +138,9 @@ Reference the appropriate resource file based on the user's needs:
| CDN & Caching | `references/storage-cdn-caching.md` | Cache control, Smart CDN, stale content |
| File Operations | `references/storage-ops-file-management.md`| Move, copy, delete, list files |

**CLI Usage:** Always use `npx supabase` instead of `supabase` for version consistency across team members.

## Supabase Documentation

Everytime something is not clear, or you want to double-check something, reference the official Supabase documentation. It is the source of truth for all things Supabase and is regularly updated with the latest information, best practices, and examples. - [Supabase Documentation](https://supabase.com/docs). The documentation is available in html format on the website, but you can also fetch plain text versions of specific sections using the following endpoints:

**Documentation:**
When something is not clear or you need to verify information, reference the official Supabase documentation — it is the source of truth. Available in plain text for easy fetching:

```bash
# Index of all available docs
Expand All @@ -115,3 +151,6 @@ curl https://supabase.com/llms/guides.txt

# Fetch JavaScript SDK reference
curl https://supabase.com/llms/js.txt
```

Full documentation: [https://supabase.com/docs](https://supabase.com/docs)
55 changes: 47 additions & 8 deletions skills/supabase/SKILL.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
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.
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. Read the development references before performing any Supabase development task — they define the correct tools, workflows, and boundaries.
license: MIT
metadata:
author: supabase
Expand All @@ -12,14 +12,44 @@ metadata:

# 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 provides several language sdks, including supabase-js and supabase-py.
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.

## Development Guidance

**Before performing any Supabase development task, read the development reference files.** They define which tools to use, how to interact with Supabase instances, and the correct workflows for local and remote development. Getting these wrong leads to schema drift, migration conflicts, and broken deployments.

- **Which tool to use for each operation** — read [references/dev-cli-vs-mcp.md](references/dev-cli-vs-mcp.md)
- **New project or first-time setup** — read [references/dev-getting-started.md](references/dev-getting-started.md)
- **Local development workflow** (CLI migrations, psql debugging, type generation) — read [references/dev-local-workflow.md](references/dev-local-workflow.md)
- **Remote project interaction** (MCP queries, logs, advisors, deploying) — read [references/dev-remote-workflow.md](references/dev-remote-workflow.md)
- **CLI command details and pitfalls** — read [references/dev-cli-reference.md](references/dev-cli-reference.md)
- **MCP server configuration** — read [references/dev-mcp-setup.md](references/dev-mcp-setup.md)
- **MCP tool usage** (execute_sql, apply_migration, get_logs, get_advisors) — read [references/dev-mcp-tools.md](references/dev-mcp-tools.md)

When the user's project has no `supabase/` directory, start with [references/dev-getting-started.md](references/dev-getting-started.md). When it already exists, pick up from the appropriate workflow (local or remote) based on user intentions.

## Overview of Resources

Reference the appropriate resource file based on the user's needs:
Reference the appropriate resource file based on the user's needs.

### Development (read first)

**Read these files before any Supabase development task.** They define the correct tools, workflows, and boundaries for interacting with Supabase instances. Start here when setting up a project, running CLI or MCP commands, writing migrations, connecting to a database, or deciding which tool to use for an operation.

| Area | Resource | When to Use |
| --------------- | ----------------------------------- | -------------------------------------------------------------- |
| Getting Started | `references/dev-getting-started.md` | New project setup, CLI install, first-time init |
| Local Workflow | `references/dev-local-workflow.md` | Local development with CLI migrations and psql debugging |
| Remote Workflow | `references/dev-remote-workflow.md` | Developing against hosted Supabase project using MCP |
| CLI vs MCP | `references/dev-cli-vs-mcp.md` | Tool roles: CLI (schema), psql/MCP (debugging), SDK (app code) |
| CLI Reference | `references/dev-cli-reference.md` | CLI command details, best practices, pitfalls |
| MCP Setup | `references/dev-mcp-setup.md` | Configuring Supabase remote MCP server for hosted projects |
| MCP Tools | `references/dev-mcp-tools.md` | execute_sql, apply_migration, get_logs, get_advisors |

### Authentication & Security

Read when implementing sign-up, sign-in, OAuth, SSO, MFA, passwordless flows, auth hooks, or server-side auth patterns.

| Area | Resource | When to Use |
| ------------------ | ----------------------------------- | -------------------------------------------------------- |
| Auth Core | `references/auth-core-*.md` | Sign-up, sign-in, sessions, password reset |
Expand All @@ -32,6 +62,8 @@ Reference the appropriate resource file based on the user's needs:

### Database

Read when designing tables, writing RLS policies, creating migrations, configuring connection pooling, or optimizing query performance.

| Area | Resource | When to Use |
| ------------------ | ------------------------------- | ---------------------------------------------- |
| RLS Security | `references/db-rls-*.md` | Row Level Security policies, common mistakes |
Expand All @@ -43,6 +75,8 @@ Reference the appropriate resource file based on the user's needs:

### Edge Functions

Read when creating, deploying, or debugging Deno-based Edge Functions — including authentication, database access, CORS, routing, streaming, and testing patterns.

| Area | Resource | When to Use |
| ---------------------- | ------------------------------------- | -------------------------------------- |
| Quick Start | `references/edge-fun-quickstart.md` | Creating and deploying first function |
Expand All @@ -63,6 +97,8 @@ Reference the appropriate resource file based on the user's needs:

### Realtime

Read when implementing live updates — Broadcast messaging, Presence tracking, or Postgres Changes listeners.

| Area | Resource | When to Use |
| ---------------- | ------------------------------------ | ----------------------------------------------- |
| Channel Setup | `references/realtime-setup-*.md` | Creating channels, naming conventions, auth |
Expand All @@ -73,6 +109,8 @@ Reference the appropriate resource file based on the user's needs:

### SDK (supabase-js)

Read when writing application code that interacts with Supabase — client setup, queries, error handling, TypeScript types, or framework integration.

| Area | Resource | When to Use |
| --------------- | ------------------------------- | ----------------------------------------- |
| Client Setup | `references/sdk-client-*.md` | Browser/server client, SSR, configuration |
Expand All @@ -84,6 +122,8 @@ Reference the appropriate resource file based on the user's needs:

### Storage

Read when implementing file uploads, downloads, image transformations, or configuring storage access control and CDN caching.

| Area | Resource | When to Use |
| --------------- | ------------------------------------- | ---------------------------------------------- |
| Access Control | `references/storage-access-control.md`| Bucket policies, RLS for storage |
Expand All @@ -94,13 +134,9 @@ Reference the appropriate resource file based on the user's needs:
| CDN & Caching | `references/storage-cdn-caching.md` | Cache control, Smart CDN, stale content |
| File Operations | `references/storage-ops-file-management.md`| Move, copy, delete, list files |

**CLI Usage:** Always use `npx supabase` instead of `supabase` for version consistency across team members.

## Supabase Documentation

Everytime something is not clear, or you want to double-check something, reference the official Supabase documentation. It is the source of truth for all things Supabase and is regularly updated with the latest information, best practices, and examples. - [Supabase Documentation](https://supabase.com/docs). The documentation is available in html format on the website, but you can also fetch plain text versions of specific sections using the following endpoints:

**Documentation:**
When something is not clear or you need to verify information, reference the official Supabase documentation — it is the source of truth. Available in plain text for easy fetching:

```bash
# Index of all available docs
Expand All @@ -111,3 +147,6 @@ curl https://supabase.com/llms/guides.txt

# Fetch JavaScript SDK reference
curl https://supabase.com/llms/js.txt
```

Full documentation: [https://supabase.com/docs](https://supabase.com/docs)
13 changes: 9 additions & 4 deletions skills/supabase/references/_sections.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,22 +15,27 @@ queries.
**Impact:** CRITICAL
**Description:** Row Level Security policies, connection pooling, schema design patterns, migrations, performance optimization, and security functions for Supabase Postgres.

## 3. Edge Functions (edge)
## 3. Development (dev)

**Impact:** CRITICAL
**Description:** Getting started with Supabase, CLI command reference, MCP server setup and tools, when to use CLI vs MCP, and development workflows for local and remote environments.

## 4. Edge Functions (edge)

**Impact:** HIGH
**Description:** Fundamentals, authentication, database access, CORS, routing, error handling, streaming, WebSockets, regional invocations, testing, and limits.

## 4. SDK (sdk)
## 5. SDK (sdk)

**Impact:** HIGH
**Description:** supabase-js client initialization, TypeScript generation, CRUD queries, filters, joins, RPC calls, error handling, performance, and Next.js integration.

## 5. Realtime (realtime)
## 6. Realtime (realtime)

**Impact:** MEDIUM-HIGH
**Description:** Channel setup, Broadcast messaging, Presence tracking, Postgres Changes listeners, cleanup patterns, error handling, and debugging.

## 6. Storage (storage)
## 7. Storage (storage)

**Impact:** HIGH
**Description:** File uploads (standard and resumable), downloads, signed URLs, image transformations, CDN caching, access control with RLS policies, and file management operations.
Loading