Conversation
Rodriguespn
force-pushed
the
feature/supabase-skill
branch
3 times, most recently
from
c9a10b7 to
6356065
Compare
Rodriguespn
force-pushed
the
feature/supabase-skill
branch
2 times, most recently
from
9cab06c to
803e968
Compare
Rodriguespn
force-pushed
the
feature/supabase-skill
branch
from
803e968 to
f856e34
Compare
Rodriguespn
force-pushed
the
feature/supabase-skill
branch
4 times, most recently
from
cd7d687 to
fff97dc
Compare
Rodriguespn
force-pushed
the
feature/supabase-skill
branch
3 times, most recently
from
397502e to
d097278
Compare
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds a Supabase skill with SKILL/AGENTS/CLAUDE docs, a references index and template, and ~49 new reference documents across Database, Edge Functions, Realtime, and Storage; also reclassifies Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~30 minutes 🚥 Pre-merge checks | ✅ 3 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 10
🤖 Fix all issues with AI agents
In `@skills/supabase/AGENTS.md`:
- Line 32: Update the example filename in AGENTS.md so it follows the
`{prefix}-{topic}.md` pattern using the `db-` prefix: replace the current
`query-missing-indexes.md` example with a `db-` prefixed name such as
`db-query-missing-indexes.md` (or `db-perf-indexes.md`) wherever the example
appears so it matches the described pattern.
In `@skills/supabase/references/db-migrations-diff.md`:
- Around line 74-92: Update the documentation under the "What diff Captures" and
"What diff Does NOT Capture" sections to explicitly list "Extensions" as a
captured item and standardize wording around RLS policy limitations: replace
informal lowercase `alter policy` with uppercase "ALTER POLICY" and clarify that
ALTER POLICY changes for RLS policies may not be captured correctly,
recommending use of versioned migrations for RLS policy modifications; update
both the capture list and the caveat paragraph and ensure the "Extensions"
bullet appears in the captured list.
In `@skills/supabase/references/db-migrations-idempotent.md`:
- Line 81: Update the broken reference in db-migrations-idempotent.md: replace
the link text "migrations-testing.md" with the correctly prefixed filename
"db-migrations-testing.md" so the reference matches AGENTS.md and other docs;
locate the occurrence of "migrations-testing.md" in the file and change it to
"db-migrations-testing.md" (ensure any markdown link syntax remains intact).
In `@skills/supabase/references/db-migrations-testing.md`:
- Line 118: Update the markdown link text so it uses the correct filename
prefix: replace the reference string "migrations-idempotent.md" with
"db-migrations-idempotent.md" in the file
skills/supabase/references/db-migrations-testing.md (look for the existing link
line that currently reads [migrations-idempotent.md](migrations-idempotent.md)
and change both the link label and target to db-migrations-idempotent.md).
In `@skills/supabase/references/db-perf-indexes.md`:
- Around line 114-115: Update the two markdown link references so they use the
documented db- prefix: change [rls-performance.md](rls-performance.md) to
[db-rls-performance.md](db-rls-performance.md) and change
[schema-jsonb.md](schema-jsonb.md) to [db-schema-jsonb.md](db-schema-jsonb.md);
ensure both link text and target filenames are updated consistently where
referenced so they match AGENTS.md naming conventions.
In `@skills/supabase/references/realtime-patterns-cleanup.md`:
- Around line 87-88: The phrase "Pay as you go" should be hyphenated as
"Pay-as-you-go" in the sentence discussing quotas and Supabase Dashboard
Realtime Settings; update the text that currently reads 'For Pay as you go
customers, stop and ask the user to edit these limits in the Supabase Dashboard
under Realtime Settings.' to use "Pay-as-you-go" so it reads 'For Pay-as-you-go
customers, stop and ask the user to edit these limits in the Supabase Dashboard
under Realtime Settings.'
In `@skills/supabase/references/realtime-patterns-errors.md`:
- Around line 45-71: Update the heartbeat callback sample to match the current
supabase-js API by changing the parameter from a client object to a status
string and using that status (values:
'sent'|'ok'|'error'|'timeout'|'disconnected') inside the handler instead of
calling client.connectionState(); update the example referencing
heartbeatCallback to demonstrate handling each status case; also review and
confirm the validity of the referenced error codes `too_many_joins` and
`tenant_events` and the stated per-connection channel limit (currently
documented as 100 in this doc) against the official Supabase Realtime and
rate-limits docs and adjust the table entries and the reconnection statement
(remove or soften the absolute claim that "No manual re-subscribe is needed") to
reflect the documented reconnection behavior.
In `@skills/supabase/references/realtime-postgres-changes.md`:
- Around line 14-16: Replace the misleading bullet "- Low user counts (< 100
concurrent subscribers per table)" with a clarification that this is an informal
performance recommendation, not a hard per-table limit; state that actual
concurrent WebSocket connection limits are plan-based (e.g., Free ≈200, Pro
≈500, higher tiers 500–10,000+ per project) and explain the rationale: each
subscriber incurs per-change RLS authorization work so you should plan lower
subscriber counts per table for predictable performance. Keep the other bullets
about DELETE events, RLS behavior, and single-threaded ordering unchanged.
In `@skills/supabase/references/realtime-presence-tracking.md`:
- Around line 75-83: In the "## Quotas" section remove or clarify the trailing
sentence that begins "For Pay as you go customers, stop and ask the user to edit
these limits in the Supabase Dashboard under Realtime Settings." — either delete
it entirely, or replace it with a clear statement identifying the intended
customer segment (e.g., "Pro (no spend cap) / Pay-as-you-go customers") and a
concrete instruction (e.g., "To adjust these limits, visit Realtime Settings in
the Supabase Dashboard"), and if you keep the "pay as you go" phrasing hyphenate
it to "Pay-as-you-go" for correctness.
In `@skills/supabase/SKILL.md`:
- Around line 21-28: The curl example in the SKILL.md docs is incorrect: the
command `curl -H "Accept: text/markdown" https://supabase.com/docs/<path>` will
not return markdown because the Supabase docs endpoint serves HTML; remove or
replace that code block. Replace it either by removing the misleading Accept
header and showing a correct fetch like `curl -L
https://supabase.com/docs/<path>` (which returns HTML), or provide an alternate
accurate workflow (e.g., fetch HTML and convert to Markdown via pandoc or
reference the official docs export/API if available). Update the SKILL.md curl
code block and surrounding text that mentions "fetch as markdown" to reflect the
correct behavior.
🧹 Nitpick comments (4)
skills/supabase/SKILL.md (1)
21-21: Consider capitalizing "Markdown" as a proper noun.When referring to the markup language/format, "Markdown" is typically capitalized as it's a proper noun (the name of the format created by John Gruber).
📝 Suggested capitalization
-You can use the `curl` commands to fetch the documentation page as markdown: +You can use the `curl` commands to fetch the documentation page as Markdown:skills/supabase/AGENTS.md (1)
11-17: Consider adding a language identifier to the directory structure code block.The static analysis tool flagged this fenced code block as missing a language specifier. While this is a directory structure visualization (not executable code), adding
textorplaintextas the language identifier would satisfy linters and is a minor improvement.🔧 Suggested addition
-``` +```text supabase/ SKILL.md # Main skill file - read this first AGENTS.md # This navigation guideskills/supabase/references/_template.md (1)
12-19: Consider using explicit column selection in the template example.The Quick Start example uses
select("*")which, while functional, isn't the recommended practice. Since this is a template that will be copied for new references, showing explicit column selection would encourage better practices from the start.💡 Suggested improvement
```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("*"); +const { data, error } = await supabase.from("table").select("id, name, created_at");This demonstrates explicit column selection, which is better for performance and security. </details> </blockquote></details> <details> <summary>skills/supabase/references/db-migrations-idempotent.md (1)</summary><blockquote> `68-71`: **Consider adding a language identifier to the migration naming example.** The static analysis tool flagged this code block as missing a language specifier. Adding `text` or `plaintext` would satisfy linters. <details> <summary>🔧 Suggested addition</summary> ```diff -``` +```text 20240315120000_create_users.sql 20240315130000_add_profiles.sql</details> </blockquote></details> </blockquote></details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Fix all issues with AI agents
In `@skills/supabase/references/db-migrations-diff.md`:
- Around line 97-98: The two broken relative links referencing
migrations-idempotent.md and migrations-testing.md should be updated to the
correct filenames db-migrations-idempotent.md and db-migrations-testing.md;
modify the link targets in the references block so the entries read
[db-migrations-idempotent.md](db-migrations-idempotent.md) and
[db-migrations-testing.md](db-migrations-testing.md) to match the actual files
in the repo.
There was a problem hiding this comment.
Actionable comments posted: 10
🤖 Fix all issues with AI agents
In `@skills/supabase/references/storage-access-control.md`:
- Around line 118-122: The relative links under the "Related" section in
storage-access-control.md are broken; update the two links that currently point
to ../db/rls-common-mistakes.md and ../db/rls-policy-types.md to the correct
filenames located in the same references/ directory: db-rls-common-mistakes.md
and db-rls-policy-types.md so the link targets match the actual files.
In `@skills/supabase/references/storage-cdn-caching.md`:
- Around line 88-91: The "Related" link in storage-cdn-caching.md points to
upload-standard.md which is inconsistent with the storage-prefixed naming used
elsewhere; update the link target (the reference currently "upload-standard.md")
to the correct storage-prefixed file name (e.g., "storage-upload-standard.md")
so the link resolves correctly, and verify the actual filename in the repo and
adjust the link accordingly.
In `@skills/supabase/references/storage-download-urls.md`:
- Around line 95-99: Update the "Related" links in storage-download-urls.md to
use the storage-prefixed filenames so they don't 404: replace
"access-control.md" with "storage-access-control.md" and "transform-images.md"
with "storage-transform-images.md" (leave the external Docs link unchanged);
ensure the link text still matches the target filenames.
In `@skills/supabase/references/storage-ops-file-management.md`:
- Around line 146-149: In the Related list inside
skills/supabase/references/storage-ops-file-management.md replace the existing
link target "access-control.md" with the storage-prefixed filename
"storage-access-control.md" so the Related entry becomes the correct reference
to storage-access-control.md (keeping the link text as-is or updating it to
"storage-access-control.md" for clarity).
In `@skills/supabase/references/storage-transform-images.md`:
- Around line 73-78: The fenced code block under "Direct URL Parameters" is
missing a language tag; update the triple-backtick fence for that URL example
(the Direct URL example block) to include a language identifier such as text
(e.g., change ``` to ```text) so markdownlint MD040 is satisfied and the block
is explicitly marked as plain text.
- Around line 113-117: Update the "Related" links to use the storage-prefixed
filenames so they resolve correctly: replace download-urls.md with
storage-download-urls.md and cdn-caching.md with storage-cdn-caching.md in the
"Related" list in storage-transform-images.md (use the same pattern applied
elsewhere in this skill).
In `@skills/supabase/references/storage-upload-resumable.md`:
- Around line 122-125: The Related section contains a broken relative link text
"upload-standard.md" that doesn't match the actual file name; update the link
target and link text to use "storage-upload-standard.md" so the entry reads "-
[storage-upload-standard.md](storage-upload-standard.md) - Small file uploads"
(edit the Related block in
skills/supabase/references/storage-upload-resumable.md where the link to
upload-standard.md appears).
- Around line 62-88: Replace the placeholder region in the S3Client constructor
(the region parameter passed when instantiating S3Client) with your actual
Supabase project region (examples: us-east-1, eu-central-1) to ensure correct
AWS Signature V4 signing; update the region value where S3Client is created and
optionally add an inline comment/example next to the region parameter to guide
developers (refer to S3Client and the endpoint using projectRef in the same
snippet).
- Around line 102-120: Update the documentation to clarify that while upload
URLs are issued as valid for 24 hours, the practical upload window may be
shorter because the Supabase Auth JWT (Bearer token) typically expires after ~1
hour by default; mention that developers must either refresh their JWT or use a
long-lived service role key when performing long resumable uploads (refer to the
"upload URLs valid for 24 hours" statement and the Auth JWT/Bearer token
behavior in the same section, and keep the note next to the TUS chunkSize
guidance such as the "chunkSize: 6 * 1024 * 1024" example).
In `@skills/supabase/SKILL.md`:
- Around line 13-19: The SKILL.md body is written in descriptive prose; rewrite
the introductory sentences into imperative commands (e.g., start with verbs) and
convert the "Overview of Resources" guidance into action-oriented
instructions—use the "Supabase" heading and the "Overview of Resources" section
as anchors to replace lines like "Supabase is an open source..." with concise
imperatives (e.g., "Use Supabase for a Postgres database, auth, instant APIs,
edge functions, realtime subscriptions, and storage." and "Reference the
appropriate resource file based on the user's needs."). Keep the content under
500 lines, prefer concise examples over long explanations, and move any detailed
material into the referenced resource files.
There was a problem hiding this comment.
Actionable comments posted: 15
🤖 Fix all issues with AI agents
In `@skills/supabase/references/_sections.md`:
- Around line 18-24: The "Storage" section heading is misnumbered as "## 3.
Storage (storage)" causing duplicate numbering with "## 3. Realtime (realtime)";
update the heading text to "## 4. Storage (storage)" so the sequence reads "##
3. Realtime (realtime)" then "## 4. Storage (storage)". Locate the heading
string "## 3. Storage (storage)" in the file and change the numeric prefix to 4,
ensuring any adjacent references or table-of-contents entries (if present) are
consistent with the new section number.
In `@skills/supabase/references/edge-adv-streaming.md`:
- Around line 1-5: The YAML frontmatter is missing a quantified benefit in
impactDescription and title should be action-oriented; update the frontmatter
fields (title, impact, impactDescription, tags) so title is an action phrase
like "Stream AI Responses via SSE", keep impact as MEDIUM, and replace
impactDescription with a quantified metric (e.g., "Reduces end-to-end latency by
~40ms per response and improves perceived responsiveness by 25% for real-time
clients"), or other measured throughput/latency numbers relevant to edge
streaming; ensure tags remain present (edge-functions, streaming, sse,
server-sent-events).
- Around line 1-5: The frontmatter title is not action-oriented; update the YAML
in skills/supabase/references/edge-adv-streaming.md so the title is a verb-led
phrase (e.g., "Stream Responses" or "Enable Streaming Responses") while keeping
the required fields intact: title, impact, impactDescription, and tags; ensure
impact uses an allowed value (CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW)
and impactDescription is a concise quantified benefit.
In `@skills/supabase/references/edge-adv-websockets.md`:
- Around line 1-5: Update the YAML frontmatter keys: change the title to an
action‑oriented phrase (e.g., "Handle WebSocket Connections" or "Implement
WebSocket Communication") by editing the title field; keep or adjust impact to
one of the allowed levels (CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW) in
the impact field if needed; and replace the current impactDescription with a
quantified benefit statement (e.g., "Reduces latency by ~50% for real-time
updates and supports X concurrent connections," or "Enables real-time
bidirectional messaging, improving update delivery for Y% of use cases") so it
clearly states the measurable outcome; ensure tags remain present and relevant
in the tags field.
In `@skills/supabase/references/edge-auth-jwt-verification.md`:
- Around line 1-5: Update the YAML frontmatter so the title is action‑oriented
(e.g., "Verify JWTs and Authenticate Edge Requests") and replace the generic
impactDescription with a quantified benefit (e.g., "Reduces unauthorized access
incidents by X% by validating JWTs at the edge" or "Prevents unauthorized access
for all edge requests by enforcing JWT verification"), while leaving impact
(CRITICAL) and tags intact; edit the frontmatter keys title, impactDescription,
impact, and tags accordingly in the existing document.
- Around line 23-27: The example calls supabase.auth.getClaims(token) even when
token may be undefined; add a guard after extracting token (from
req.headers.get("Authorization")?.replace("Bearer ", "")) that returns new
Response("Missing token", { status: 401 }) (or similar 401) when token is falsy,
and only then call supabase.auth.getClaims(token) and proceed to use
data.claims.sub.
In `@skills/supabase/references/edge-auth-rls-integration.md`:
- Around line 1-5: Update the YAML frontmatter so the title is verb-led (e.g.,
"Integrate RLS into Edge Functions") instead of a noun phrase, keep impact set
to one of the allowed levels (HIGH is acceptable) and replace impactDescription
with a concise, quantified benefit (e.g., "Reduces risk of unauthorized row
access by X% or prevents Y classes of data leaks per deployment"), and ensure
tags remain present; modify the frontmatter keys title, impact,
impactDescription, and tags accordingly in the file.
- Around line 31-40: The example uses req.headers.get("Authorization")! which
can be null and is not guarded; before calling createClient inside Deno.serve,
check for the presence of the Authorization header (e.g., const auth =
req.headers.get("Authorization")) and if missing return a 401 response
immediately, only then pass the validated auth value into createClient
(global.headers.Authorization) so createClient never receives a null/undefined
header.
In `@skills/supabase/references/edge-db-direct-postgres.md`:
- Around line 1-5: Update the YAML frontmatter so the title is action-oriented
and the impactDescription is quantified: change the title field to an action
verb phrase (e.g., "Connect Directly to Postgres from Edge Functions") and
rewrite impactDescription to state a measurable benefit (e.g., "Reduces latency
by X% and enables Y concurrent connections" or "Enables complex queries and ORM
usage, improving developer productivity by X%"); ensure you update the existing
title and impactDescription keys in the frontmatter accordingly.
- Around line 34-43: The example creates a new postgres client per-request
inside Deno.serve which breaks pooling; move the postgres(...) client creation
and the drizzle(client) call to module scope (outside Deno.serve) so the same
client is reused across requests, remove any per-request .end() calls, and
configure the client with idle_timeout and max_lifetime options (e.g.,
idle_timeout and max_lifetime passed into postgres(...)) to allow automatic
cleanup of idle connections; update references to the existing db and users
usage inside the Deno.serve handler to use the module-scoped db instance.
In `@skills/supabase/references/edge-db-supabase-client.md`:
- Around line 33-37: The code currently force-unwraps
req.headers.get("Authorization") when calling createClient (supabase), which
will throw on unauthenticated requests; change it to read the header into a
variable (e.g., const auth = req.headers.get("Authorization")), and only include
the Authorization header in the global headers object if auth is truthy (or omit
headers entirely when absent) so that createClient/supabase initialization does
not crash for unauthenticated requests.
In `@skills/supabase/references/edge-dbg-limits.md`:
- Around line 1-5: Update the YAML frontmatter to make the title action-oriented
and to quantify the impactDescription: change the title field to an
imperative/action phrase (e.g., "Mitigate Edge Function Debugging Limits" or
similar) and rewrite impactDescription to include a measurable benefit (e.g.,
"Reduces production failures by X% and speeds debugging by Y hours per
incident") so both `title` and `impactDescription` comply with the
reference-file guidelines.
In `@skills/supabase/references/edge-fun-project-structure.md`:
- Around line 1-5: The frontmatter uses a non-action title and an unquantified
impactDescription; update the YAML so `title` is action-oriented (e.g., start
with a verb like "Optimize", "Organize", or "Reduce") and change
`impactDescription` to quantify the benefit (e.g., "Reduces cold start latency
by X% and improves maintainability by Y") while keeping existing fields (`tags`,
`impact`) intact; specifically edit the `title` and `impactDescription`
frontmatter keys in this file so they comply with the reference-file
requirements.
In `@skills/supabase/references/edge-fun-quickstart.md`:
- Around line 1-5: Update the YAML frontmatter: change the title field to an
action-oriented phrase (e.g., start with a verb like "Deploy Edge Functions:
Quickstart" or "Quickstart — Deploy Edge Functions") and replace the
impactDescription with a quantified benefit (e.g., "Enables developers to deploy
production-ready Edge Functions in under 15 minutes, reducing deployment
friction by X%") so both title and impactDescription fields are present and meet
the guideline; modify the existing title and impactDescription keys in the
frontmatter accordingly.
In `@skills/supabase/references/edge-pat-routing.md`:
- Around line 1-5: Update the YAML frontmatter: change the title to an
action-oriented phrase (e.g., "Route Edge PATs with Multi-Route Functions" or
similar) and replace the generic impactDescription with a quantified benefit
(include numeric metrics or percentages and timeframe, e.g., "Reduces cold-start
latency by ~30% and simplifies API maintenance, lowering operational overhead by
X%"). Ensure you edit the frontmatter keys `title` and `impactDescription` in
this file so they follow the reference-file requirements and include concrete,
quantifiable outcomes.
🧹 Nitpick comments (4)
skills/supabase/references/edge-dbg-testing.md (2)
2-2: Make the title action‑oriented.“Testing Edge Functions” is descriptive; the guideline expects an action‑oriented title (verb‑led).
As per coding guidelines "Reference files must include YAML frontmatter withtitle(action-oriented)".
4-4: Quantify the impact description.The impactDescription should include a measurable/quantified benefit, not just a qualitative statement.
As per coding guidelines "Reference files must include YAML frontmatter withimpactDescription(quantified benefit)".Proposed tweak
-impactDescription: Ensures reliability before production deployment +impactDescription: Reduces local test failures by ~X% before production deploymentskills/supabase/references/edge-db-supabase-client.md (1)
1-5: QuantifyimpactDescriptionper guidelines.
impactDescriptionneeds a quantified benefit; the current text is qualitative. Please update it to include a measurable impact (even if approximate).
As per coding guidelines: “Reference files must include YAML frontmatter withtitle(action-oriented),impact(CRITICAL|HIGH|MEDIUM-HIGH|MEDIUM|LOW-MEDIUM|LOW),impactDescription(quantified benefit), andtags(keywords)”.✅ Example update
-impactDescription: Primary method for database operations with RLS support +impactDescription: Enables 100% RLS-enforced database operations from Edge Functionsskills/supabase/references/edge-adv-websockets.md (1)
39-46: Consider passing the JWT explicitly togetClaims()for clarity and consistency.The
jwtparameter in supabase-js v2'sgetClaims()is optional, so the current example works with the Authorization header. However, the JWT is already extracted and available on line 35. For consistency with the pattern shown inedge-auth-jwt-verification.md, pass it explicitly:Suggested improvement
- const { data, error } = await supabase.auth.getClaims(); + const { data, error } = await supabase.auth.getClaims(jwt);
Rodriguespn
force-pushed
the
feature/supabase-skill
branch
from
5bf5ee3 to
3e05038
Compare
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
The model cannot access the Supabase Dashboard directly, so instruct it to ask the user to perform dashboard actions instead. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* rebase and house keeping * fix: storage reference accuracy after docs review Fix RLS permission mappings, CDN cache behavior, file management limits, image transform descriptions, and S3 upload API signatures based on official Supabase documentation audit. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix offset * fix move and copy instructions --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
* rebase and house keeping * fix edge functions reference files after docs review * update agents.mdd
* rebase and house keeping * fix supabase sdk reference files after docs review * update agents.md
* feat: auth agent references * Update skills/supabase/references/auth-core-sessions.md Co-authored-by: Stojan Dimitrovski <sdimitrovski@gmail.com> * refactor: improve auth state management and update session handling examples * docs: update performance note for asymmetric JWTs * fix: correct signOut() default scope to 'global' signOut() defaults to scope: 'global' (all sessions on all devices), not current session only. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: improve signOut() examples to show all three scope options Replace redundant explicit 'global' example with 'local' scope, making all three options (global, local, others) visible. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * refactor: flatten auth references to root references directory Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * correct auth hooks * correct auth server ssr * fix auth reference files * fix paths inside skill.md * update agents.md --------- Co-authored-by: Greg Richardson <greg.nmr@gmail.com> Co-authored-by: Stojan Dimitrovski <sdimitrovski@gmail.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Rodriguespn
force-pushed
the
feature/supabase-skill
branch
from
92fcd19 to
6bb9a7c
Compare
* rebase and house keeping * wip: cli developement guides * update agents.md * fix developement workflows * fix: update SKILL.md, dev-mcp-setup, and rebuild AGENTS.md files Fix unclosed code block in SKILL.md Supabase Documentation section. Update dev-mcp-setup.md to remove security rule about restricting MCP features and add validation-compliant examples. Regenerate AGENTS.md files with new build system structure (H1 title, Overview section). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix: update SKILL.md, development references, and rebuild AGENTS.md Restructures SKILL.md to load development guidance first, updates dev-cli-reference, dev-cli-vs-mcp, dev-getting-started, dev-local-workflow, and dev-mcp-tools references with corrected workflows and tool roles. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * minor changes to mcp setup guide * update agents.md --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
| license: MIT | ||
| metadata: | ||
| author: supabase | ||
| version: '1.0.0' |
There was a problem hiding this comment.
Can we call this 0.1.0 until we feel its in a stable place?
| ### MCP (database interaction and debugging) | ||
|
|
||
| | Operation | Tool | Command | | ||
| | --- | --- | --- | | ||
| | Run SQL queries (non-schema) | MCP | `execute_sql({ project_id, query })` | | ||
| | View service logs | MCP | `get_logs({ project_id, service })` | | ||
| | Security/performance check | MCP | `get_advisors({ project_id })` | | ||
| | Inspect tables | MCP | `list_tables({ project_id })` | | ||
| | List migrations | MCP | `list_migrations({ project_id })` | |
There was a problem hiding this comment.
I'm having some second thoughts on documenting MCP in skills. From what I gather, agent skills do not version well. Specifically I mean that if someone installs these skills via npx skills ..., they will get a copy of these skills on disk that won't be updated unless they remember to update them.
I'm worried that documenting our MCP like this will force us to support tools in their current form and treat any changes as breaking changes. Up until now MCP has been great in that it is self-documenting, so we've never really had to care about breaking changes. As an example for why this is important right now, we were hoping to maybe deprecate list_tables and replace it with something more generic across all PG objects. We've also considered changing how logs work, and how search_docs works. My worry is that documenting them in a skill creates a snapshot of the tools at the time the user downloads the skill, then will confuse the LLM in the future when those tools are no longer available.
There was a problem hiding this comment.
Maybe instead of referencing specific MCP tools / arguments in skills, we more broadly describe what the agent should do, with the expectation that it'll adapt given the latest tools. E.g. instead of providing examples that explicitly show "Call 'list_tables()' ..." syntax we tell it to"List tables ...". I def agree that this section which enumerates the available tools and their purpose is redundant w/ what the MCP server already documents.
There was a problem hiding this comment.
Yeah that sounds reasonable. @Rodriguespn any thoughts on this?
| - [references/db-migrations-idempotent.md](references/db-migrations-idempotent.md) — required DDL patterns | ||
| - [references/db-rls-mandatory.md](references/db-rls-mandatory.md) — RLS enforcement rules | ||
| - [references/db-rls-common-mistakes.md](references/db-rls-common-mistakes.md) — critical security errors to avoid |
There was a problem hiding this comment.
Just had a thought - we're treating SKILL.md as an index to find further references (which is the right approach I think). What if instead of bundling these reference files inside the skill, we host these reference files at something like https://supabase.com/skills/references/db-migrations-idempotent? Exact same content, but the LLM just needs to make a fetch request instead of a file read? This way we can easily keep the reference files up to date with latest content without worrying about content going stale.
There was a problem hiding this comment.
I am totally on board with that ☝️ Even the index can be hosted on our site (basically just LLMs.txt with info tailored for agents).
That's similar to how MoltBook works, they host a https://moltbook.com/skill.md which is the installation entrypoint. Once running, the agent periodically fetches a https://www.moltbook.com/heartbeat.md file fresh from the web for up to date instructions.
Once we have markdown versions of our docs pages being served, I imagine there can be a lot of overlap between "skill references" and regular docs pages.
There was a problem hiding this comment.
there can be a lot of overlap between "skill references" and regular docs pages.
Agreed, though my gut is that we likely still want some kind of compact / LLM-focused version of our docs like we're attempting right now with our reference files. Could be wrong though!
There was a problem hiding this comment.
Even the index can be hosted on our site (basically just LLMs.txt with info tailored for agents).
This one I'm not completely following though - wouldn't we need some index locally that the LLM would load into its context intially? We could have a tiny skill file that says "fetch https://supabase.com/skill.md", but now we're asking the LLM to make one extra tool call just to load the index into context, which feels a bit risky given tendencies for models to avoid extra docs-related tool calls.
There was a problem hiding this comment.
I think I’m mostly aligned with both of you, but I want to separate a few concerns.
On keeping SKILL.md clean + moving references remotely, I agree with keeping SKILL.md lightweight and moving the reference files to our domain. We’ve talked before about where these should live, and I still think hosting them under something like supabase.com/skills/... makes the most sense. It gives us the ability to iterate quickly without worrying about stale snapshots floating around in users’ node_modules.
I also like the pattern Neon is using in their agent skills, where SKILL.md acts as a navigator that clearly explains how to traverse their documentation for agents rather than embedding everything inline:.
Personally, I’d lean toward hosting the index remotely as well. If the concern is an extra fetch call, I think the tradeoff (freshness + central control) is worth it.
Alternative: versioned docs inside the npm package
There’s also another viable path: bundle agent-focused docs inside the npm package and have SKILL.md point to something like:
node_modules/<package-name>/docsThis is similar to what Vercel is doing with the AI SDK skills.
The advantage here is strong version alignment. The docs shipped with a given package version are guaranteed to match the MCP/tooling behavior for that version. That neatly solves the “snapshot” concern because the snapshot is intentional and versioned.
If we went this route though, I don’t think those embedded docs should just be markdown exports of our public docs. They should be explicitly structured for agents — closer to our current reference file format: compact, task-oriented, and opinionated about how to use the tools.
One more thought: what about llms.txt?
If we move toward skill-style reference files hosted on our domain, should we consider replacing or evolving our current llms.txt to follow the same structure?
It might be cleaner long-term to unify these into a single, agent-optimized documentation surface that both skills and general LLM consumption rely on. Otherwise, we risk maintaining parallel “LLM docs” that slowly diverge.
Curious how you both feel about consolidating around one agent-focused format instead of having llms.txt + skill references as separate tracks.
There was a problem hiding this comment.
Repurposing llms.txt to be this index is a really interesting idea. We could literally update it to be what currently lives in this PR's SKILL.md, and it references files that are in nested /llms/* folders?
versioned docs inside the npm package
I've thought about this quite a bit lately, and I think it makes a lot of sense for scoped packages and libraries (like the ai-sdk) which are 100% focused on that library and 1:1 versioned with the library.
So for us, I think this idea makes sense for our CLI-specific instructions, but it doesn't feel quite right for more the higher level cross-cutting guides/best practices across Supabase (like what this Supabase skill aims to do). To me those type of guides should live on the web.
I’d lean toward hosting the index remotely as well.
I love the idea from a maintainability perspective, but still a bit concerned on whether LLMs will actually fetch it. Maybe the best way to know is to do some tests: one with the index embedded into the skill, and one where the index lives remotely and the skill is a ~one liner asking the LLM to fetch it? If there is any model that doesn't fetch this >95% of the time, it's probably not worth it?
There was a problem hiding this comment.
Vercel's web design guidelines SKILL.md uses the "fetch fresh content everytime you use the skill" pattern:
## Guidelines Source
Fetch fresh guidelines before each review:
```
https://raw.githubusercontent.com/vercel-labs/web-interface-guidelines/main/command.md
```
Use WebFetch to retrieve the latest rules. The fetched content contains all the rules and output format instructions.4 participants
What kind of change does this PR introduce?
Adds the
supabaseagent skill — a comprehensive guide for AI agents working with Supabase products — and refactors the build system to produce leaner AGENTS.md output.What is the current behavior?
There is no skill available to guide AI agents on how to properly use Supabase products. The build system generates verbose AGENTS.md files that duplicate reference file listings.
What is the new behavior?
This PR adds the complete
supabaseskill with 84 reference files across 7 categories covering Auth, Database, Development Workflows (CLI/MCP), Edge Functions, supabase-js SDK, Realtime, and Storage. It also refactors the build system so AGENTS.md is generated from the SKILL.md body content rather than auto-enumerating every reference file, and adds new validation rules (name/directory match, H1 heading requirement, kebab-case checks).Reference breakdown
auth-db-dev-edge-sdk-realtime-storage-Key changes
skills/supabase/SKILL.mdskills/supabase/references/_sections.mddefinitions +_template.mdfor contributorsskills/supabase/AGENTS.mdpackages/skills-build/src/build.tsparseSkillFrontmatter,skillNameToTitle; addedextractSkillBody,parseSkillBodySectionspackages/skills-build/src/validate.tsvalidateSkillStructure— validates name/directory match, kebab-case format, and H1 heading consistencyskills/supabase-postgres-best-practices/AGENTS.md