postgres-best-practices

Supabase Agent Skills

Agent Skills to help developers using AI agents with Supabase. Agent Skills are folders of instructions, scripts, and resources that agents can discover and use to do things more accurately and efficiently. Compatible with 18+ AI agents including Claude Code, GitHub Copilot, Cursor, Cline, and many others.

The skills in this repo follow the Agent Skills format.

Installation

See the Supabase AI Skills documentation for detailed installation instructions.

Install all skills

npx skills add supabase/agent-skills

Install a specific skill

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

Claude Code Plugin

You can also install the skills as Claude Code plugins:

# 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

Available Skills

Usage

Skills are automatically available once installed. The agent will use them when relevant tasks are detected.

Examples:

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

Skill Structure

Each skill follows the Agent Skills Open Standard:

• SKILL.md - Required skill manifest with frontmatter (name, description, metadata)
• references/ - (Optional) Reference files for detailed documentation

.well-known discovery

Each release uploads a dist/index.json alongside the skill tarballs. This index conforms to the agent-skills .well-known URI spec (schema v0.2.0) and is consumed by supabase.com to serve skills at https://supabase.com/.well-known/agent-skills/.

The release artifacts are built by scripts/build-release.ts and triggered by Release Please on every semver release.

Migrating to the official GitHub Action

jonathanhefner/agentskills-build-for-well-known is intended to be transferred to the agentskills org and published to the GitHub Marketplace. When that happens, scripts/build-release.ts and the pnpm build:release step in release-please.yml can be replaced with the Action directly:

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

Everything else — the Release Please trigger, the upload step, the supabase-plugin dispatch — stays exactly the same. The script and the Action produce identical output, so it is a drop-in swap.