supabase-specialist

Production Postgres and Supabase patterns for AI agents — RLS, migrations, dual-client auth, RPC atomicity, and serverless connection pooling. Part of the BrewHub PHL specialist skill fleet.

Install

Cursor / Claude Code (recommended)

npx skills add brewhubphl/supabase-specialist

Install to a single project:

npx skills add brewhubphl/supabase-specialist --path .agents/skills

Manual

git clone https://github.com/brewhubphl/supabase-specialist.git
cp -R supabase-specialist ~/.cursor/skills/supabase-specialist
# or symlink into your repo: .agents/skills/supabase-specialist

Usage

Invoke explicitly so the agent loads the skill on demand:

Use the supabase-specialist skill to review this migration for RLS gaps.

@supabase-specialist Design an RPC for idempotent webhook processing with advisory locks.

The agent should read SKILL.md first, then pull only the relevant patterns/*.md file — not the entire tree.

Repository layout

├── SKILL.md                 # Entry point + YAML frontmatter
├── AGENTS.md                  # Navigation for agents
├── anti-patterns.md           # Consolidated mistakes
├── patterns/                  # Deep dives (load on demand)
├── references/                # Official links, glossary, book summaries
├── examples/                  # Cross-stack integration
├── brew-hub-overrides/        # Optional product-specific notes
└── scripts/validate-skill.mjs # CI validation

Extending with books (book-to-skill)

This repo includes 50 chapter summaries from The Art of PostgreSQL. To extend:

1. Add a chapter summary under references/book-summaries/<book>-ch<N>.md using the template in that folder.
2. Promote durable rules into patterns/ when they become standards.
3. Add recurring mistakes to anti-patterns.md.
4. Open a PR — CI runs node scripts/validate-skill.mjs.

Keep SKILL.md lean; book content stays modular.

BrewHub philosophy

This skill teaches generic Supabase excellence. BrewHub-specific patterns (dual-client tool factories, rate-limit RPCs, payment locks) live in examples/brew-hub-integration.md as abstract architecture — no live fleet hostnames or secrets in public repos.

For a private product overlay, copy brew-hub-overrides/ into an internal repo or layer skills:

.agents/skills/
├── supabase-specialist/          # this repo (public)
└── brewhub-supabase-overrides/   # your private repo

Related specialists

Repo	Domain
nextjs-specialist	App Router, Server Actions
cloudflare-specialist	Workers, pooling at the edge
python-ai-agents-specialist	ADK tools → same RPC contracts

Development

node scripts/validate-skill.mjs

License

MIT — see LICENSE.