`supabase/agent-skills`: the official skill that stops your agent from shipping broken RLS

Your agent just created a Supabase table. The migration ran clean. The Dashboard shows the table. The RLS policy looks right. The REST endpoint returns an empty array.

This is the most common AI-generated Supabase failure pattern, and it's not a model capability problem. According to Pedro Rodrigues, AI Tooling Engineer at Supabase: "Every model applied security_invoker correctly when the skill was available. They knew how to implement it. They just didn't know when." 1

supabase/agent-skills (v0.1.5, MIT, released May 27, 2026) is Supabase's official answer: a two-skill bundle that teaches your agent the when, not just the how. 2

github.com · GitHub 仓库

supabase/agent-skills

https://github.com/supabase/agent-skills

正在加载内容卡片…

What it includes

The repo ships two independent skills you can install together or separately:

supabase (v0.1.2) covers the full product surface — Auth, Database, Edge Functions, Realtime, Storage, Vectors, Cron, Queues — plus client-library guidance (supabase-js, @supabase/ssr) and framework integrations (Next.js, React, SvelteKit, Astro, Remix). Its SKILL.md description field is what the agent reads to decide whether to activate: trigger keywords cover every Supabase product name, auth operations (getSession, getUser, JWT, RLS), CLI commands, and MCP server interactions. No slash command required — the skill activates automatically when the agent detects a Supabase task. 3

supabase-postgres-best-practices (v1.1.1) is an eight-tier optimization guide for Postgres, ranked by impact: Query Performance and Connection Management at CRITICAL, Schema Design at HIGH, Concurrency at MEDIUM-HIGH, down to Advanced Features at LOW. Each rule ships with a broken SQL example, a corrected version, and a sample EXPLAIN output so the agent can reason about tradeoffs rather than just copy-paste answers. 4 The postgres skill already has 199,100 installs on skills.sh, ranking 34th across all skills on the platform. 5

Both skills follow the Agent Skills Open Standard and work across 20 agents: Claude Code, Cursor, Codex, GitHub Copilot, Windsurf, Cline, Gemini, Goose, Roo, VS Code, Zed, and more. 2

Why this release landed when it did

Today (May 30, 2026) is the cutover date for a Supabase platform change that breaks every AI-generated migration that relies on training data: new projects no longer auto-expose tables through PostgREST / GraphQL / supabase-js. Any CREATE TABLE without explicit GRANT statements returns empty results from the REST API — no error thrown, just silence. 6

Matthew Diakonov of Fazm describes the failure mode precisely: "The migration applies, the dashboard shows the table, the row level security policies look correct, and the REST endpoint returns an empty result set. The failure mode reads like a policy bug, which sends a developer down the wrong investigation path." 6

The fix is three GRANT statements that belong in every new-project migration:

GRANT SELECT ON public.invoices TO anon;
GRANT SELECT, INSERT, UPDATE, DELETE ON public.invoices TO authenticated;
GRANT SELECT, INSERT, UPDATE, DELETE ON public.invoices TO service_role;

v0.1.5 — published three days before the cutover — adds these grants to the security checklist. With the skill loaded, Claude Code generates them automatically alongside the CREATE TABLE. Without the skill, it generates the migration it learned from older training data: table, RLS enabled, policy written, grants absent. 6

Install

The fastest path is a single command:

npx skills add supabase/agent-skills

That installs both skills at project scope (placing them in your repo so teammates and cloud agents share the same setup). To install globally across projects, add --global. To install only one skill:

npx skills add supabase/agent-skills --skill supabase
npx skills add supabase/agent-skills --skill supabase-postgres-best-practices

Claude Code plugin marketplace (alternative path):

claude plugin marketplace add supabase/agent-skills
claude plugin install supabase@supabase-agent-skills
# or
claude plugin install postgres-best-practices@supabase-agent-skills

After installing via the plugin marketplace, run /reload-plugins to activate. 7

You can also grab the Supabase Plugin for AI Coding Agents, which bundles the MCP Server and both skills into one install — useful if you want the database query tools and the development guidance together. 8

What changes in your agent's output

Rodrigues ran a four-model eval on Supabase tasks, comparing three conditions: no tools, MCP only, and MCP + skill. The results across all models consistently favored the skill condition: 1

Model	Baseline	MCP only	MCP + Skill
Claude Code (Sonnet 4.6)	46%	58%	71%
Claude Code (Opus 4.6)	58%	50%	67%
Codex (GPT-5.4)	71%	71%	88%
Codex (GPT-5.4 Mini)	42%	63%	71%

One finding stood out: Claude Code (Opus 4.6) actually dropped from 58% to 50% in the MCP-only condition. Rodrigues's explanation: "MCP alone is not enough. Without workflows or guidelines, agents guess at how to combine tools." 1 The MCP-only agents also never called search_docs to verify current documentation, defaulting to training data instead.

The security checklist embedded in the supabase skill (inlined directly into SKILL.md so the agent cannot skip it) covers 15+ rules across five categories:

Auth and sessions: never use user_metadata for JWT-based authorization (users can edit it); use app_metadata instead; deleting a user does not invalidate existing tokens — shorten JWT lifetime if needed
API key exposure: never ship service_role key to the client
RLS and views: views bypass RLS by default — use WITH (security_invoker = true) on Postgres 15+; UPDATE policies require a matching SELECT policy or silently return 0 rows; auth.role() is deprecated, use TO authenticated
Storage: upsert requires INSERT + SELECT + UPDATE — all three, not just INSERT
Supply chain (new in v0.1.5): always pin package versions and commit the lockfile 9

Shubh Thorat, a FAANG engineer who covers the agent tooling space, put the design choice plainly: "The skills layer on top of MCP is what makes this feel different. MCP handles the plumbing but skills give the agent actual context for when and how to use it." 10

View on X

正在加载内容卡片…

Pedro Rodrigues covered the full skill design and eval loop — including the write skill → run eval → inspect results → iterate cycle using Braintrust — at the AI Engineer channel's "Skill Issue" workshop (9,500 views). 11

Honest limitations

The skills repo has 12 open issues and a 14% close rate (2 closed out of 14 filed). v0.1.5 shipped exactly one new feature and resolved none of the backlog. Four open issues are worth knowing before you commit: 12

Pooler cluster ambiguity (issue #92): When a new project lands on a non-default cluster (aws-1-, aws-2-), the skill's connection guidance still points to aws-0-. The error message Tenant or user not found reads like a credentials problem, not a host problem. One user spent 25 minutes on this before finding the answer in supabase/discussions#30107. 13

13 correctness issues in the postgres reference docs (issue #83): A CodeRabbit automated review found errors including ALTER SYSTEM not available on managed Postgres, inaccurate index claim for wildcard LIKE, and a VACUUM lock statement written incorrectly. These are in the reference files (loaded on-demand), not the main SKILL.md, so they only surface when the agent reaches those specific optimization topics. 14

Three security gaps not yet in the checklist (issue #63): RLS self-referential policies on a profiles table trigger Postgres infinite recursion detected; new projects use ES256 JWTs that Edge Function gateways reject unless you deploy with --no-verify-jwt; frontend calls to Edge Functions need both Authorization and apikey headers, but the skill only documents one. 15

pg_uuidv7 extension unavailable (issue #70): The postgres skill recommends uuid_generate_v7() via pg_uuidv7, which is not available on Supabase managed Postgres. Agents following this guidance generate migrations that fail to execute. 16

The skills repo is 4.5 months old with an actively shipping team (5 releases since April 9). These gaps are real but the resolution pace suggests they'll close over the next few minor versions.

When NOT to use this skill

You're not using Supabase. The supabase skill activates on Supabase keyword detection; on a raw Postgres or PlanetScale project it adds noise without value. The supabase-postgres-best-practices skill is more general but still Supabase-opinionated in its examples and caveats.

Your project was created before May 30, 2026. Existing projects retain the old Data API behavior (auto-exposed tables) until October 30, 2026. The v0.1.5 GRANT guidance won't break old-project migrations, but agents may over-generate grants that aren't needed. Test one migration first.

You're building advanced auth flows. The three security gaps in issue #63 are real — RLS self-reference, ES256 JWT handling, and the dual-header Edge Function requirement are all common patterns in production auth systems. Load the skill, but manually verify the agent's output against the Supabase docs for these specific patterns.

You need an ops / DBA-grade Postgres config. The postgres skill's ALTER SYSTEM, pg_uuidv7, and some VACUUM guidance contain errors on managed Supabase Postgres. For schema design and query optimization the skill is reliable; for connection pool tuning and low-level Postgres config, cross-check against the actual Supabase Docs.

Repo: supabase/agent-skills · 2,172 ★ · MIT · v0.1.5 (May 27, 2026) · Open issues: #92 (pooler), #83 (postgres docs), #63 (auth gaps), #70 (uuid)