supabase/agent-skills: Official Supabase Guidance for AI Coding Agents

Every AI agent already knows Postgres. What it does not reliably know is Supabase: which auth cookies matter, when getSession versus getUser is the right call, how RLS policies interact with client libraries, where the performance cliffs are. supabase/agent-skills — 2.6k stars — is Supabase's official fix: agent skills written by the platform team, following the open Agent Skills standard, compatible with 18+ AI agents including Claude Code, GitHub Copilot, Cursor, and Cline.

Why This Skill Matters

There are two skills, and they solve different failure modes. The umbrella supabase skill covers all Supabase products — Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron, Queues — plus client libraries (supabase-js, @supabase/ssr) across Next.js, React, SvelteKit, Astro, and Remix. It is what you want when an agent is wiring up auth or reaching for the CLI and MCP server. The supabase-postgres-best-practices skill is narrower and deeper: Postgres performance guidelines from Supabase, organized as 8 reference categories prioritized by impact — Query Performance, Connection Management, and Security & RLS are all marked Critical; Schema Design and Concurrency & Locking follow.

Both follow the standard skill structure — a SKILL.md manifest plus optional references/ files — so each loads only the detail it needs.

Installation

Install everything:

npx skills add supabase/agent-skills

Or just one skill:

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

Claude Code users can go through the plugin marketplace instead:

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

Detailed install instructions live in Supabase's AI Skills documentation.

Real Workflow: Review a Schema Before Launch

You are about to ship a feature with a hand-written migration and want the performance and RLS angle covered.

1. Install the best-practices skill (the targeted install keeps your agent's context lean).
2. Prompt the agent:

Review my schema for performance issues

3. Follow up with Help me add proper indexes to this table for anything the review flags.

The skill pulls from the prioritized categories, so queries and connection handling get checked before the low-impact advanced features.

Real Workflow: Wire Up Auth in Next.js

The README's example prompt covers the whole setup path:

Help me set up Supabase Auth with Next.js

The umbrella skill knows the @supabase/ssr integration and the auth gotchas — sessions, JWT handling, cookies — which is exactly the territory where agents otherwise produce plausible-but-wrong code.

Tips

• Install selectively: the umbrella skill for app-building sessions, the Postgres skill for query and schema work — the README itself recommends picking what you need.
• Supabase publishes a discovery index at supabase.com/.well-known/agent-skills/, conforming to the agent-skills .well-known URI spec.
• The skill triggers automatically once installed — no special prefix needed in prompts.
• Releases are automated through Release Please, with skill tarballs and an index built per semver release.

When Not to Use This

The guidance is Supabase-shaped. The Postgres best-practices skill is oriented around Supabase's platform — connection pooling, RLS conventions, its extensions — so a plain-vanilla Postgres project elsewhere will find parts of it irrelevant. If you are not using Supabase at all, a general Postgres skill serves you better.

See the leaderboard for more skills.