supabase/agent-skills ships two markdown folders and a build script written for its own removal

Two folders ship, and the plugin names are not the folder names

The repository publishes exactly two skills. The first, `supabase`, is scoped across the whole product surface: Database, Auth, Edge Functions, Realtime, Storage, Vectors, Cron and Queues, plus the supabase-js and @supabase/ssr client libraries in Next.js, React, SvelteKit, Astro and Remix, auth troubleshooting around sessions, JWT, cookies, getSession, getUser, getClaims and RLS, the Supabase CLI or MCP server, and schema changes, migrations, security audits and extensions such as pg_graphql, pg_cron and pg_vector.

The second, `supabase-postgres-best-practices`, grades its own material by impact. Its eight reference categories carry explicit priorities: Query Performance (Critical), Connection Management (Critical), Security and RLS (Critical), Schema Design (High), Concurrency and Locking (Medium-High), Data Access Patterns (Medium), Monitoring and Diagnostics (Low-Medium), Advanced Features (Low). Three of eight carry the top mark and the last one is explicitly the last place to look.

What matters for anything that automates this is that two different strings point at the second folder. The npx installer takes `--skill supabase-postgres-best-practices`, while the Claude Code plugin line calls the same content `postgres-best-practices@supabase-agent-skills`. The `supabase-` prefix vanishes in the plugin form and then comes back as the marketplace name. A script that matches folder names will miss plugin names, and nothing in the repository warns about it.

The TypeScript in the repository builds the index, not the skills

The package is labelled TypeScript and the tree carries a `scripts/` directory, but what a developer installs is markdown. `package.json` declares no `dependencies`, no `main`, no `bin` and no exports map. Every dependency it does declare is a development tool: `@types/node`, `gray-matter`, `tar`, `tsx`, `typescript` and `vitest`.

Three scripts are defined, and all three are maintenance chores rather than a compile step. `test` runs `vitest run`, `test:sanity` narrows that to `test/sanity.test.ts`, and `build:release` runs `tsx scripts/build-release.ts`. Nothing in the manifest emits the skill content itself: there is no bundler, no transpile target and no packing command, so the tarballs that ship are produced by that single tsx invocation at release time.

The consequence for a reviewer is that the only substantive TypeScript in the repository is release plumbing, and everything a user actually reads lives under `skills/`. For a document set that agents pull into a context window and act on, having almost no runtime code to audit is a genuine advantage rather than a gap.

The installation section is one link out, and no command pins a version

The Installation heading contains one sentence and one address: see the Supabase AI Skills documentation for detailed installation instructions, pointing at `https://supabase.com/docs/guides/getting-started/ai-skills`. That same URL is the homepage field in the repository metadata, so the project points at its own documentation site and leaves the rest of the walkthrough to that page.

What the repository does spell out are three install paths, and not one of them carries a version, a tag or a commit:

npx skills add supabase/agent-skills

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

The release pipeline underneath is semver based. v0.1.7 shipped on 2026-07-30, v0.1.8 on 2026-08-12 and v0.1.9 on 2026-09-28. So the artifacts are versioned while the line a user copies is not, and nothing in the repository explains how to hold a skill at v0.1.7 once a newer default branch head lands.

The third path is the Claude Code route, which needs two steps in a fixed order, a marketplace registration first and the plugin second:

# 1. Install supabase/agent-skill marketplace
claude plugin marketplace add supabase/agent-skills

# 2. Install the plugin that you want
claude plugin install supabase@supabase-agent-skills
claude plugin install postgres-best-practices@supabase-agent-skills

The first comment names the marketplace as `supabase/agent-skill`, without the final s, so the identifier in the comment and the identifier in the command beside it are not the same string. Read the commands rather than the comments.

The shipped artifact is a .well-known index, and its spec is an open pull request

Behind the skills sits a discovery index. Each release uploads a `dist/index.json` alongside the skill tarballs, and that index is what `supabase.com` reads in order to serve skills at `https://supabase.com/.well-known/agent-skills/`. The shape of the file is described as the agent-skills `.well-known` URI spec at schema v0.2.0, and the link given for that spec points at a pull request, `agentskills/agentskills` number 254, rather than at a released specification.

So the published contract is a versioned schema number attached to an unmerged proposal. The repository does not describe how a change to that proposal would reach anything that already consumed v0.2.0, and it does not list which fields a consumer may rely on.

The artifacts come out of `scripts/build-release.ts`, triggered by Release Please on every semver release, with `.release-please-manifest.json` and `release-please-config.json` at the root pinning the versioning scheme. The manifest value and the release stream agree right now: the package declares 0.1.9 and the newest tag is v0.1.9, so there is no version drift to reconcile today. That is a small thing, but it is the kind of alignment that quietly stops being true in repositories where a package is published from a branch and tags are cut by hand.

The build script already carries instructions for its own removal

A section of the README describes a migration that has not happened yet. `jonathanhefner/agentskills-build-for-well-known` is named as a project intended to be transferred to the `agentskills` organization and published to the GitHub Marketplace. Once that happens, `scripts/build-release.ts` and the `pnpm build:release` step in `release-please.yml` are meant to be replaced by the Action:

- name: Build release artifacts
  uses: agentskills/build-for-well-known@v1   # replaces pnpm build:release
  with:
    skills-dir: skills
    output-dir: dist

The surrounding pipeline is explicitly untouched. The Release Please trigger, the upload step and the supabase-plugin dispatch all stay as they are, and the two implementations are said to produce identical output, which makes the swap a drop-in.

Two details deserve attention before treating that as settled. The Action reference is `agentskills/build-for-well-known@v1`, an organization and tag that do not resolve until the transfer lands, so today's release path still runs the local tsx script and the migration is a plan rather than a state. And the identical-output claim is a statement in prose: the only test hooks named anywhere in `package.json` are `vitest run` and a sanity run against `test/sanity.test.ts`, and neither is described as comparing build output.

Skills trigger themselves, and the examples show nothing but prompts

There is no command to run a skill and no command to list what is installed. The stated behaviour is that skills are automatically available once installed, and that the agent uses them when relevant tasks are detected. Detection is the entire activation mechanism, and nothing in the repository documents a manual invocation, an inventory command, or a way to switch off a skill that keeps matching.

The four examples given are bare prompts, each in its own fence:

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

Not one of them names a skill, so there is no way to tell from the prompt which folder an answer came from, or whether it came from either. That matters here because the two folders differ in depth and emphasis rather than in subject: the graded skill marks three areas Critical and puts Advanced Features last, while the general skill spans the entire product line at one level.

The required structure is small by design. Each skill needs a `SKILL.md` manifest with name, description and metadata frontmatter, and may carry a `references/` directory. The opening line of the project describes a skill as a folder of instructions, scripts and resources, yet scripts have no slot in that two item structure.

509 open issues, three agent instruction files, and an unexplained .mcp.json

The repository carries 2692 stars, 216 forks and 509 open issues. Set that against what actually ships, two folders of markdown, and the issue count points at everything surrounding the content rather than at the content itself.

Three instruction files sit at the root for the agents that work on this repository, `AGENTS.md`, `CLAUDE.md` and `CONTRIBUTING.md`, next to `CHANGELOG.md` and a `.claude-plugin/` directory that matches the plugin route documented for Claude Code. `.mcp.json` also sits at the root, and the `supabase` skill lists working with the Supabase CLI or MCP server among its triggers. No section of the project explains what that file configures or which server it names, and the file tree carries no MCP server implementation, so `.mcp.json` is the only trace of that trigger.

The test surface is similarly undocumented. `vitest.config.ts` and a `test/` directory are present at the root, and the two script names `test` and `test:sanity` are the only indication of what they cover. Anyone adopting these skills will find the content easy to read and the surrounding tooling largely unexplained.

Editorial conclusion

Install it if your agents work against Supabase, but pick the folder you actually need and read it before you trust it. Three things to check first: the second skill goes by two different identifiers depending on which install path you use, none of the install commands pins a version even though releases are semver tagged, and the .well-known index this repository publishes claims conformance to schema v0.2.0 of a specification that is still an open pull request. The script that produces that index is written to be replaced once an external Action moves into the agentskills organization, so the packaging is set to change underneath you while the markdown stays put. The licence is MIT and there is no runtime dependency to audit.

Frequently asked questions

Official sources

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