supabase-server

A project-specific guide for writing server-side code with the @supabase/server package, which creates Supabase clients and handles authentication in backends such as webhooks and edge functions.

In plain words
What is it for?
Use it when writing or changing backend code that imports @supabase/server, creates Supabase clients, validates incoming authentication, or migrates the old allow setting to auth.
Why use it?
It clarifies the package’s current options and authentication names, including which older settings are deprecated. It keeps new code aligned with the project’s available documentation and source code.

Skill for Claude CodeCodex

Install

Getting it into your agent

One page per mod, every tool's command on it. A separate URL per tool would split the same page into five that compete with each other.

agentmods
npx agentmods add skills/supabase/server/supabase-server
Any agent
npx skills add supabase/server --skill supabase-server
Clone the repo
git clone --depth 1 https://github.com/supabase/server

Made for: Claude Code, Codex.

Per session 298 Skills are progressive disclosure: only the name and description are preloaded; the body loads when the skill is used.
When invoked 4,878 The whole file, excluding the scripts and references it only reads on demand.
Security scan B 1 finding. Scan, not verified.
Origin original No closer match found in the catalogue.
Token cost

What it costs to keep this loaded

Counted locally with the o200k_base tokenizer, which is exact for GPT models; Claude uses its own tokenizer and its counts differ. Treat this as one consistent yardstick across the catalogue rather than a bill. Prices are per million input tokens.

ModelPer sessionOnce invoked
Fable 5 $0.00298 $0.04878
Opus 5 $0.00149 $0.02439
Sonnet 5 $0.00060 $0.00976
Haiku 4.5 $0.00030 $0.00488

Measured yesterday against content hash a5050c0ba63d, method: parsed. Prices are Anthropic first-party input rates as of 2026-08-30, from the pricing page.

Security

Grade B, and why

supabase-server scanned grade B with 1 finding against 26 rules in 11 categories — prompt injection, anti-refusal, data exfiltration, privilege escalation, supply chain, agent snooping, system-prompt leakage, SSRF and excessive agency — measured yesterday.

A static scan of the body, not an audit. Every finding is printed with the line that produced it so you can judge whether it matters here. A mod is markdown that instructs an agent; that is exactly why what it instructs is worth reading.

Sends data to an external URLmediumData exfiltration

A POST to an outside endpoint may be telemetry or may be exfiltration; either way the mod talks to somewhere, and you should know where.

await fetch('https://<project>.supabase.co/functions/v1/my-function', { method: 'POST',
skills/supabase-server/SKILL.md · 428 lines

How it starts

The opening of the file, as written. The whole thing — 428 lines — stays where its author put it; the contents beside it link to each section on GitHub.

@supabase/server

v1.0 — Public Beta. First stable release under SemVer: breaking changes only ship as a major bump. The package is still early — expect new adapters, ergonomic improvements, and features to land frequently in minor releases. If you encounter a bug or rough edge while writing code with it, surface it to the user with a pointer to open an issue.

This is a brand new package. There is no information available online yet — no blog posts, no Stack Overflow answers, no tutorials. Do not search the web for usage examples. Rely exclusively on the documentation files listed below and the source code in this repository.

The config option is auth, not allow. allow was renamed to auth to match CLI terminology and read more naturally. The legacy allow key still works (with a one-time console.warn) but is deprecated and will be removed in a future major release. Always emit auth in new code — e.g. withSupabase({ auth: 'user' }, ...). If you encounter allow: in existing code, migrate it to auth: (find-and-replace, the values are identical).

Auth mode values: 'none' (not 'always'), 'publishable' (not 'public'). The four valid values are 'user', 'publishable', 'secret', 'none'. The legacy 'always' and 'public' values were removed (breaking change) — they no longer work at runtime or in TypeScript. Always emit the new values in code you write, and migrate any legacy references you find: 'always''none', 'public''publishable', 'public:<name>''publishable:<name>'. Runtime checks like ctx.authType === 'public' must also be updated to ctx.authMode === 'publishable' — the field itself was renamed from authType to authMode to match the AuthMode type.

Do not use legacy Supabase keys. The anon key and service_role key (env vars SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY) are legacy and will be deprecated. Do not use them unless the user explicitly asks. Always use the new API keys:

Legacy (avoid) New (use this)
SUPABASE_ANON_KEY SUPABASE_PUBLISHABLE_KEY(S) (sb_publishable_...)
SUPABASE_SERVICE_ROLE_KEY SUPABASE_SECRET_KEY(S) (sb_secret_...)

Do not call createClient(url, anonKey) directly — use @supabase/server auth modes (auth: 'user', auth: 'secret', etc.) which handle key resolution automatically. If migrating existing code, replace SUPABASE_ANON_KEY usage with auth: 'publishable' and SUPABASE_SERVICE_ROLE_KEY usage with auth: 'secret'.

Server-side utilities for Supabase. Handles auth, client creation, and context injection so you write business logic, not boilerplate.

Read the full file on GitHub · 428 lines

Changes

What this file has done since we first saw it

Hashed on every crawl. A supply-chain change to an agent config is a question of when, not whether, so the history is kept rather than the latest state alone.

  1. yesterday First seen · 428 lines · 298 tokens per session scan B a5050c0ba63d

Subscribe to this mod's changes

supabase-server is a skill published in the GitHub repository supabase/server (87 stars, last pushed 3d ago), licensed MIT. It adds 298 tokens to every session and 4,878 once invoked, about $0.0015 per session on Opus 5. A static security scan graded it B with 1 finding (sends data to an external url). No closer match exists in the catalogue, so it is treated as the original; first seen 2026-08-30.

Related

Other skills, from other repositories

systematic-debugging

Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes.

obra/superpowers · 21 tokens

next-cache-components-adoption

Turn on Cache Components in a Next.js app and resolve the blocking routes it surfaces. Use when the user wants to enable, adopt, or migrate to Cache Components, flip the cacheComponents flag, work through a flood of blocking-prerender / instant validation errors, run the cache-components-instant-false codemod, or…

vercel/next.js · 95 tokens

babysit-pr

Babysit a GitHub pull request after creation by continuously polling review comments, CI checks/workflow runs, and mergeability state until the PR is merged/closed or user help is required. Diagnose failures, retry likely flaky failures up to 3 times, auto-fix/push branch-related issues when appropriate, and keep…

openai/codex · 114 tokens

imagegen

Generate or edit raster images when the task benefits from AI-created bitmap visuals such as photos, illustrations, textures, sprites, mockups, or transparent-background cutouts. Use when Codex should create a brand-new image, transform an existing image, or derive visual variants from references, and the output…

openai/codex · 113 tokens

cpu-profile-analysis

Analyze V8/Chrome CPU profiles (.cpuprofile) and DevTools trace files (Trace-.json). Use when: profiling performance, investigating slow functions, comparing code paths, finding bottlenecks, analyzing timeToRequest, understanding call trees from sampling profiler data, analyzing layout/paint/rendering, investigating…

microsoft/vscode · 71 tokens

next-cache-components-optimizer

Drive a Next.js route to instant navigation by setting up an agentic loop, under Cache Components / PPR, on initial load (hard navigation) and client-side navigation (soft navigation). Encode the goal as a failing @next/playwright instant() e2e and work it to green, one verified route at a time; the shipped test then…

vercel/next.js · 170 tokens