supabase/agent-skills: Supabase and Postgres guidance for AI coding agents

What supabase/agent-skills is, and who it is for

This repository publishes two Agent Skills for developers who write Supabase code with an AI agent sitting in the editor. The first, named supabase, is described as a comprehensive development skill covering every Supabase product: Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron and Queues, plus the client libraries supabase-js and @supabase/ssr across Next.js, React, SvelteKit, Astro and Remix. The second, supabase-postgres-best-practices, is narrower and opinionated: Postgres performance guidelines arranged in eight categories and prioritized by impact, from Query Performance and Connection Management down to Advanced Features.

The audience is specific. You need an agent that reads the Agent Skills format, and you need to be doing Supabase work where the agent would otherwise guess. The README lists compatibility with 18+ AI agents including Claude Code, GitHub Copilot, Cursor and Cline. If you are hand-writing SQL and reading the Supabase docs yourself, nothing here changes your day. The repository is a distribution channel for instructions, not a tool you run.

How the skills are structured and discovered

Each skill is a folder. The README states that every skill follows the Agent Skills Open Standard and contains a required SKILL.md manifest with frontmatter carrying name, description and metadata, plus an optional references/ directory for detailed documentation. The repository keeps these under skills/, and the top level also holds AGENTS.md, CLAUDE.md and a .claude-plugin/ directory, which is how the same content is exposed to Claude Code as a plugin.

Discovery happens two ways. Locally, the agent scans installed skill folders and picks one when it judges the task relevant; the README says skills are automatically available once installed and the agent will use them when relevant tasks are detected. Remotely, each release uploads a dist/index.json alongside the skill tarballs. That index conforms to the agent-skills .well-known URI spec at schema v0.2.0 and is consumed by supabase.com to serve skills at https://supabase.com/.well-known/agent-skills/. The artifacts are built by scripts/build-release.ts, triggered by Release Please on every semver release. That build script is the only real machinery in the repository, and the README notes it is intended to be replaced by the agentskills/build-for-well-known GitHub Action, which the README says produces identical output.

Installing supabase/agent-skills and running a first task

The README defers detailed installation to the Supabase AI Skills documentation and gives the command-line path directly. Installing everything pulls both skills into your agent's skill directory. The skills CLI is invoked through npx, so no global install is required.

npx skills add supabase/agent-skills

If you only want the Postgres guidance, the --skill flag narrows the install. The README shows both skill names in that form.

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

Claude Code users have a second path through the plugin marketplace. The README gives a two-step sequence: register the marketplace, then install the plugin you want.

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

After installation, the README says the skills are available automatically and the agent selects them when it detects a relevant task. The README's own examples of prompts are plain English rather than commands: "Optimize this Postgres query", "Review my schema for performance issues", "Help me set up Supabase Auth with Next.js", "Help me add proper indexes to this table". Expect the agent to pull in the Postgres skill for the first two and the broader Supabase skill for the third. There is no CLI to run and no output to inspect; the visible result is a different answer in your chat window.

The Postgres skill is prioritized, and that is the interesting design choice

Most prompt packs are flat lists of advice. supabase-postgres-best-practices is ordered by impact, with Query Performance, Connection Management and Security & RLS marked Critical, Schema Design marked High, Concurrency & Locking Medium-High, Data Access Patterns Medium, Monitoring & Diagnostics Low-Medium, and Advanced Features Low. That ordering is a real constraint on the agent's attention: when a context window is finite, a skill that ranks its own contents gives the agent a way to spend that budget on the parts that matter first.

The trade-off is that the ranking is a judgement made by the maintainers and shipped as static text. If your workload is dominated by something the list places at Low, such as an advanced Postgres feature, the skill will still surface it, but only after the Critical material. There is no documented mechanism in the README for reweighting the categories per project. You can read the references/ files directly, but that is you reading documentation, not the agent applying it.

Where the repository stops: no runtime, no verification, no rollback

Nothing in this repository connects to your database. It contains instructions, scripts and resources, and the scripts it does contain are release tooling: build-release.ts, a vitest suite, and the Release Please configuration. If you want something that parses your SQL, measures a query plan, or refuses a migration that drops an index, this is the wrong tool. The agent may still produce a bad index recommendation; the skill changes the prior, it does not check the answer.

The README does not document rollback or uninstall for the skills CLI, and it does not describe what happens when two installed skills give conflicting advice. It also does not state how the agent resolves a version mismatch between an installed skill and the Supabase client library in your project. Those are the gaps to weigh before you put this in front of a team. On maintenance: the repository is not archived, and the last push was on 2026-08-12, which is recent enough that the content reflects current Supabase surfaces, but the version number is still 0.1.8, so treat the skill text as pre-1.0 material that can change shape between releases.

How this compares to a general-purpose skills collection

The obvious alternative is a broad agent-skills library, the kind curated around general engineering practice rather than one vendor's stack. The difference is scope and specificity. A general collection spreads its instructions across languages, frameworks and tooling, which means the agent gets a shallow prior on everything. supabase/agent-skills goes the other way: two skills, one vendor, and inside the Postgres skill an explicit impact ranking. If your work is Supabase-heavy, the narrower skill should produce more targeted advice about RLS policies, connection pooling and index choice than a general pack would.

The cost is the mirror image. A general library still helps when you move to a different backend, and it will not carry vendor-shaped assumptions into unrelated code. There is also a middle option the README itself points at: agentskills.io hosts the format specification, and the .well-known index that supabase.com serves means you can consume the skills remotely rather than vendoring them. Pick the vendor-specific pack when Supabase is the stack; pick a general pack when it is one of several.

Licence, upgrade cost and what a release actually changes

The repository is MIT licensed, and package.json declares the same. For most teams that means you can copy the skill folders into an internal repository, modify the instructions, and ship them to your own agents without a redistribution question. The usual caveat applies and is not legal advice: MIT covers the repository contents, and the Supabase name and marks are a separate matter if you republish under your own branding.

Upgrade cost is low but not zero. Releases are cut by Release Please on semver tags, and the changelog lives in CHANGELOG.md. Because the artifacts are just Markdown and reference files, an upgrade is a re-run of the install command or a pull of the new tarballs; there is no migration step and no API surface to break. The thing to watch is behavioural: a reworded SKILL.md description changes when the agent decides the skill is relevant, and a reordered category list changes what the agent reads first. Diff the skill folders between releases rather than trusting the version bump.

Editorial conclusion

Adopt it if your team already drives Supabase work through an agent that follows the Agent Skills format, and you want Postgres indexing, RLS and connection pooling advice inside the same conversation as the code. Skip it if you expect a runtime dependency, a linter, or anything that inspects a live database, because the repository contains instructions and reference files only. Before installing, check the Supabase AI Skills documentation for the exact install path for your agent, confirm the last push date against your own tolerance for staleness, and read the SKILL.md frontmatter of the skill you plan to use to see what it actually claims to cover.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. supabase/agent-skills on GitHub