
`supabase/agent-skills` (v0.1.5, MIT, May 27, 2026) is Supabase's official two-skill bundle — `supabase` and `supabase-postgres-best-practices` — that teaches Claude Code, Cursor, Codex, and 17 other agents *when* to apply Supabase-specific security rules, not just *how*. Released three days before Supabase's May 30 Data API cutover (new projects no longer auto-expose tables), the skill patches the silent-fail `GRANT` gap that breaks every pre-skill migration. Eval data from Supabase shows Claude Code (Sonnet 4.6) jumping from 46% → 71% completion rate with the skill loaded. The article covers both skills, all install paths, the four concrete open-issue caveats (#92 pooler cluster ambiguity, #83 incorrect postgres docs, #63 auth security gaps, #70 uuid extension), and four specific "when NOT to use" scenarios.
security_invoker correctly when the skill was available. They knew how to implement it. They just didn't know when." 1supabase/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. 2supabase (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. 3supabase-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. 5supabase-js. Any CREATE TABLE without explicit GRANT statements returns empty results from the REST API — no error thrown, just silence. 6GRANT 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;CREATE TABLE. Without the skill, it generates the migration it learned from older training data: table, RLS enabled, policy written, grants absent. 6npx skills add supabase/agent-skills--global. To install only one skill:npx skills add supabase/agent-skills --skill supabase
npx skills add supabase/agent-skills --skill supabase-postgres-best-practicesclaude plugin marketplace add supabase/agent-skills
claude plugin install supabase@supabase-agent-skills
# or
claude plugin install postgres-best-practices@supabase-agent-skills/reload-plugins to activate. 7| 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% |
search_docs to verify current documentation, defaulting to training data instead.supabase skill (inlined directly into SKILL.md so the agent cannot skip it) covers 15+ rules across five categories: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 neededservice_role key to the clientWITH (security_invoker = true) on Postgres 15+; UPDATE policies require a matching SELECT policy or silently return 0 rows; auth.role() is deprecated, use TO authenticatedINSERT + SELECT + UPDATE — all three, not just INSERTwrite skill → run eval → inspect results → iterate cycle using Braintrust — at the AI Engineer channel's "Skill Issue" workshop (9,500 views). 11aws-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. 13ALTER 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. 14profiles 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. 15pg_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. 16supabase 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.GRANT guidance won't break old-project migrations, but agents may over-generate grants that aren't needed. Test one migration first.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.github.com
raw.githubusercontent.com
raw.githubusercontent.com
supabase.com
raw.githubusercontent.com
x.com
github.com
This story was produced automatically by a channel. One sentence is all it takes for Neodrop to keep producing for you.