Supabase Agent Skills

What It Does

Supabase maintains two agent skills in this repo. The supabase skill (132-line SKILL.md) covers the full Supabase platform: database, auth, storage, realtime, edge functions, vectors, cron, and queues. It includes security checklists, CLI usage guidance, MCP server setup instructions, and a feedback loop for reporting incorrect guidance. The supabase-postgres-best-practices skill (64-line SKILL.md) serves as an index into 31 reference files covering 8 categories of Postgres optimization: query performance, connection management, schema design, locking, data access patterns, monitoring, security, and advanced features. Both follow the Agent Skills Open Standard (agentskills.io).

The repo includes a CI pipeline with sanity tests (7 tests, all passing) that verify npx skills add installs the correct skills into the correct directories. Release automation uses Release Please for semver versioning and GitHub Actions for tarball generation and downstream sync.

The Good

Best-in-class security content. The supabase skill dedicates roughly half its body to security gotchas specific to the Supabase platform. It covers user_metadata injection via JWT claims, stale session tokens after user deletion, views bypassing RLS, UPDATE requiring SELECT policies, SECURITY DEFINER functions being callable by anon/authenticated roles, and the deprecation of auth.role(). Each gotcha includes a concrete SQL example showing both the wrong and the right way. This is not boilerplate security advice. It is Supabase-specific knowledge that would catch real vulnerabilities.

Well-structured progressive disclosure. The supabase skill stays lean at 132 lines and delegates to a single reference file (skill-feedback.md) only when needed. The postgres-best-practices skill uses the reference system more aggressively: 31 files across 8 categories, each with impact-prioritized frontmatter (CRITICAL through LOW). An agent only loads the top-level index (64 lines) and pulls individual rules on demand. The frontmatter on each reference file includes title, impact level, impact description, and tags, giving the agent enough metadata to decide whether to load without reading the full file.

Reference file quality is high. Each of the 31 postgres reference files follows a consistent template: a 1-2 sentence explanation, an "Incorrect" SQL example with a comment explaining the problem, a "Correct" SQL example with a comment explaining the fix, and a documentation link. Some files include EXPLAIN output showing the performance difference. The incorrect/correct pattern makes the rules unambiguous for an agent to follow. File sizes are tight: 40 to 80 lines each, no filler.

Install and CI are solid. The npx skills add flow works cleanly. I tested both full install (both skills) and single-skill install. Both completed without errors in under 3 seconds. The CI test suite (7 tests in sanity.test.ts) verifies skill discovery, installation, per-skill install, and SKILL.md presence. All 7 pass. The repo also includes a .mcp.json pointing to the Supabase MCP server, a .claude-plugin/marketplace.json for Claude Code plugin discovery, and a build-release.ts script that produces tarballs with SHA-256 digests and an index.json conforming to the agentskills discovery schema v0.2.0.

Vendor commitment signals. 2,138 stars, MIT license, active CI, Release Please automation, a feedback issue template, and a dedicated reference file that walks agents through filing GitHub issues for incorrect guidance. The repo also has AGENTS.md (symlinked as CLAUDE.md) with detailed contribution guidelines. This is not a weekend project.

The Bad

Only two skills in the pack. For a repo with 2,138 stars and the Supabase brand behind it, the coverage is narrow. The description claims coverage of "Database operations, auth, storage, realtime, and edge functions," but there is no dedicated skill for storage policies, realtime subscription patterns, edge function deployment, or vector/ai operations. The supabase skill tries to cover everything in 132 lines. It works as a reference, but a developer doing complex storage or realtime work will outgrow the single-file guidance quickly.

The supabase skill lacks references. The postgres-best-practices skill has 31 reference files. The supabase skill has one: skill-feedback.md (which is about filing bugs, not about using Supabase). All the security checklists, CLI guidance, MCP setup, and migration instructions live in the single SKILL.md body. An agent loading this skill gets the full 132 lines every time, even if it only needs the auth section. Compare this to the postgres skill, which loads 64 lines and pulls references on demand.

No version pinning or changelog in skill content. The SKILL.md frontmatter has metadata.version but the skill body says "Supabase changes frequently" and instructs the agent to fetch the changelog. That is honest but creates a dependency on network access at runtime. If the agent cannot reach supabase.com, it falls back to potentially stale training data. The skill does not ship with a version-specific reference snapshot.

Description field is verbose for the supabase skill. At 475 characters, it is well under the 1024-char limit, but it reads like a keyword list rather than a natural description. The postgres-best-practices skill has a cleaner 183-char description that covers both what and when.

Smoke Test Results

We ran structural validation on the cloned repo and a hands-on install test on the host (macOS, aarch64, Node.js v24.13.1).

Structural validation

$ head -8 skills/supabase/SKILL.md | grep -c "^name: supabase$"
✅ PASS: name field present and matches directory

$ head -8 skills/supabase/SKILL.md | grep -c "^description:"
✅ PASS: description field present (475 chars)

$ head -12 skills/supabase-postgres-best-practices/SKILL.md | grep -c "^name: supabase-postgres-best-practices$"
✅ PASS: name field present and matches directory

$ head -12 skills/supabase-postgres-best-practices/SKILL.md | grep -c "version:"
✅ PASS: version metadata present

$ ls skills/supabase-postgres-best-practices/references/*.md | wc -l
✅ PASS: 31 reference files found (excluding _meta files)

$ ls skills/supabase/references/*.md | wc -l
✅ PASS: 1 reference file found (skill-feedback.md)

$ grep -c "^title:" skills/supabase-postgres-best-practices/references/query-missing-indexes.md
✅ PASS: reference files have title frontmatter

$ grep -c "^impact:" skills/supabase-postgres-best-practices/references/query-missing-indexes.md
✅ PASS: reference files have impact frontmatter

$ wc -l skills/supabase/SKILL.md skills/supabase-postgres-best-practices/SKILL.md
✅ PASS: both under 500-line limit (132, 64)

$ test -f .mcp.json && echo "found" || echo "missing"
✅ PASS: MCP config present

$ test -f .claude-plugin/marketplace.json && echo "found" || echo "missing"
✅ PASS: Claude plugin marketplace manifest present

Pass rate: 11 of 11. All structural checks pass. Frontmatter is consistent, naming conventions are followed, reference files have required fields, and agent discovery files are present.

Install verification

$ cd /tmp/supabase-smoke-test && npx skills add /tmp/supabase-skills-r3 -a claude-code -y
✅ PASS: both skills installed (supabase + supabase-postgres-best-practices)

$ cd /tmp/supabase-smoke-single && npx skills add /tmp/supabase-skills-r3 -a claude-code --skill supabase -y
✅ PASS: single skill install works, only supabase installed

$ find /tmp/supabase-smoke-test/.claude/skills -name "SKILL.md" | wc -l
✅ PASS: 2 SKILL.md files found in install target

$ find /tmp/supabase-smoke-test/.claude/skills -type f | wc -l
✅ PASS: 38 files installed (2 SKILL.md + 31 references + 4 assets/meta)

Pass rate: 4 of 4. Install works for both full and single-skill modes. File counts match source.

Test suite verification

$ cd /tmp/supabase-skills-r3 && pnpm install && pnpm test
✅ PASS: 7 tests pass (discover skills, install all, install per-skill, SKILL.md presence, no skill-creator leak)

Pass rate: 1 of 1. CI test suite passes clean.

What the runs tell you

Structural validation confirms the repo follows its own conventions consistently. Install verification proves npx skills add works end to end. The CI test suite covers the install flow more rigorously than we could in a manual pass. The only gap is functional: we could not test the SQL examples or auth guidance against a live Supabase project, so the correctness of the content is trusted on the strength of the Supabase team's authorship and the 31-rule template consistency.

Setup Walkthrough

1. Install via npx: npx skills add supabase/agent-skills (requires Node.js). Both skills install in under 3 seconds.
2. For a single skill: npx skills add supabase/agent-skills --skill supabase or --skill supabase-postgres-best-practices.
3. For Claude Code users: claude plugin marketplace add supabase/agent-skills then claude plugin install supabase@supabase-agent-skills.
4. No configuration needed. Skills are auto-discovered by compatible agents based on the description triggers in frontmatter.
5. The .mcp.json in the repo root points to https://mcp.supabase.com/mcp?features=docs. If your agent supports MCP, the Supabase MCP server provides additional tools (search_docs, execute_sql, get_advisors) beyond what the skills contain.

Alternatives

1. anthropics/skills -- broader coverage across more tools and platforms, but less Supabase-specific security depth. Better for general-purpose agent augmentation.
2. vercel-labs/agent-skills -- similar vendor-authored pattern (Vercel instead of Supabase). Good if your stack is Vercel-heavy. Both packs complement each other.
3. DenisSergeevitch/agents-best-practices -- general agent best practices with no vendor lock-in. Useful as a layer underneath vendor-specific packs like this one.