supabase/agent-skills: Packaging Supabase Knowledge for AI Coding Agents

The problem is documentation that agents never read

An AI agent asked to write a Supabase query has no reliable way to know which Postgres behaviours Supabase cares about, how Row-Level Security interacts with client libraries, or which connection pooling settings matter at scale. The model either guesses from training data that may be stale, or the developer pastes documentation into the prompt and repeats that work in every session. This repository takes the second path and makes it reusable. It packages instructions and reference files into folders that an Agent Skills compatible client can discover on its own. The audience is narrow and specific: developers using AI agents on Supabase projects, particularly those working across Auth, Edge Functions, Realtime, Storage, and Postgres schema design in the same codebase. If you write Supabase code without an agent, nothing here changes your workflow.

Two skills, one broad and one opinionated about performance

The repository ships two skills. The first, named supabase, is described as a comprehensive development skill covering all Supabase products and integrations. Its stated use cases include client libraries and SSR integrations such as supabase-js and @supabase/ssr in Next.js, React, SvelteKit, Astro, and Remix, plus troubleshooting auth flows involving login, logout, sessions, JWT, cookies, getSession, getUser, getClaims, and RLS. It also covers the Supabase CLI, the MCP server, schema changes, migrations, security audits, and Postgres extensions including pg_graphql, pg_cron, and pg_vector. The second skill, supabase-postgres-best-practices, is narrower and structured differently. According to the README it contains references across 8 categories prioritized by impact, listed as Query Performance (Critical), Connection Management (Critical), Schema Design (High), Concurrency and Locking (Medium-High), Security and RLS (Critical), Data Access Patterns (Medium), Monitoring and Diagnostics (Low-Medium), and Advanced Features (Low). That priority ordering is the most concrete editorial decision in the repository. It tells you the maintainers expect query and connection problems to matter more than advanced feature usage, and it gives an agent a ranking to apply when advice conflicts.

SKILL.md is the unit of distribution

Each skill follows the Agent Skills Open Standard. The required piece is a SKILL.md manifest with frontmatter carrying name, description, and metadata. An optional references directory holds longer documentation that the agent can consult when the manifest alone is not enough. That structure is why the same repository can serve 18 or more different agents, as the README claims, without per-agent forks: the client is responsible for reading the folder format, and the repository stays a plain directory tree. The practical consequence is that the quality of a skill lives almost entirely in the description field. A vague description means the agent never selects the skill for the task at hand, and the reference files sit unread. The README does not reproduce the actual frontmatter text for either skill, so you cannot judge description quality from the repository page alone. You have to open the SKILL.md files.

Installing with npx skills or as a Claude Code plugin

Installation goes through the skills CLI. Installing everything is one command: npx skills add supabase/agent-skills. To take only one skill, pass the skill flag, for example npx skills add supabase/agent-skills --skill supabase or npx skills add supabase/agent-skills --skill supabase-postgres-best-practices. Claude Code users have a second route through the plugin marketplace. The README gives three commands: claude plugin marketplace add supabase/agent-skills, then claude plugin install supabase@supabase-agent-skills, and claude plugin install postgres-best-practices@supabase-agent-skills. Note the naming mismatch between the two paths. The CLI skill names are supabase and supabase-postgres-best-practices, while the plugin names are supabase and postgres-best-practices, and the marketplace handle is supabase-agent-skills even though the repository is agent-skills. If you script installation, use the exact strings from the README rather than deriving one name from the other. Once installed, the README states that skills are automatically available and the agent uses them when relevant tasks are detected. There is no configuration key to set and no registration step documented.

The release pipeline is the part with real engineering in it

Every semver 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 produced by scripts/build-release.ts, triggered by Release Please on each release. This matters because it decouples skill consumption from GitHub. An agent or a website can fetch a single index over HTTPS instead of cloning the repository or resolving a tag. The README also notes a planned migration: the maintainers intend to replace scripts/build-release.ts and the pnpm build:release step in release-please.yml with the GitHub Action jonathanhefner/agentskills-build-for-well-known once it moves to the agentskills org and is published to the Marketplace. The README states the script and the Action produce identical output, so the swap is presented as drop-in, with the Release Please trigger, the upload step, and the supabase-plugin dispatch unchanged. Treat that as an intention, not a completed migration. The repository still builds release artifacts from its own TypeScript script as of the last push recorded here.

Where this approach breaks down

Skills are advisory. The agent decides whether to open the folder, and nothing in the format forces it to follow what it reads. A model that ignores the supabase-postgres-best-practices priority ordering will produce the same mediocre query it would have produced without the skill installed. The repository also carries no test suite or evaluation harness that the README mentions, which means there is no published evidence about whether installing these skills changes agent output. The release cadence is another signal worth reading carefully. Versions v0.1.6, v0.1.7, and v0.1.8 landed on 2026-07-10, 2026-07-30, and 2026-08-12 respectively, all under a 0.1.x version line. Frequent patch releases at 0.1.x suggest the content is still settling, so pinning a version is more sensible than tracking the default branch. Finally, the repository is the wrong tool if your problem is deterministic. If you need every generated query to pass a linter or a migration to be validated before it runs, a skill folder will not do that. You want a schema linter or a CI check, not instructions an agent may or may not read.

Alternative: writing your own skill folder

The obvious alternative is to write a SKILL.md yourself, scoped to your own schema and conventions. The difference is one of generality versus fit. This repository is maintained by Supabase and covers the whole product surface, from Auth cookie handling to pg_vector and the CLI, which is exactly what you want when your agent is working across unfamiliar parts of the platform. It cannot know that your team names tables in snake_case, that your RLS policies follow a particular helper-function pattern, or that your connection pooling goes through a specific proxy. A local skill folder can encode those rules and will be shorter, which matters because a shorter manifest is easier for an agent to apply consistently. The two are not exclusive. Installing supabase/agent-skills gives you baseline coverage of the platform, and a project-level skill can layer your conventions on top. The cost of the local route is maintenance: you own the accuracy of every claim in the file, and Postgres and Supabase behaviour changes.

Licence, maintenance and what to verify

The repository is MIT licensed, which permits commercial use, modification, and redistribution provided the copyright notice and permission notice are retained. That is permissive enough for internal tooling and for vendoring the skill folders into a private repository. It also means the skills come with no warranty, and the MIT text disclaims liability for the guidance they contain. This is not legal advice; check how your organisation handles third-party content that flows into prompts and generated code. Maintenance cost is low if you consume releases, since installation is a single CLI command and updates arrive through the same channel. It rises if you fork the skill folders to add your own conventions, because you then have to reconcile your edits with upstream changes. The migration to the official GitHub Action, if it happens, is the one upstream change that could affect a fork of the build pipeline rather than the skill content. Before adopting, verify three things: that your agent client is one of the 18 or more the README says are compatible, that the frontmatter descriptions in each SKILL.md are specific enough for your client to select the right skill, and whether you want the pinned release artifacts from dist/index.json or the working tree from the main branch.

Editorial conclusion

Adopt this if your team already uses an Agent Skills compatible client and you want Supabase and Postgres guidance available without pasting documentation into prompts. Do not adopt it if your agents run in a harness that cannot read SKILL.md folders, or if you need deterministic query rewriting rather than model-directed suggestions. Before rolling it out, install with npx skills add supabase/agent-skills into a scratch project, confirm which client discovers the skills, and check whether the release artifacts at dist/index.json match the skill versions you expect.

Official sources

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