supabase/agent-skills：给 AI 编码 agent 的 Supabase 官方指南

每个 AI agent 都懂 Postgres。它不稳定懂的是 Supabase：哪些 auth cookie 重要、什么时候该用 getSession 而不是 getUser、RLS 策略怎么和客户端库交互、性能悬崖在哪里。supabase/agent-skills——2.6k 星——是 Supabase 的官方解法：由平台团队撰写的 agent skill，遵循开放的 Agent Skills 标准，兼容 18 个以上的 AI agent，包括 Claude Code、GitHub Copilot、Cursor 和 Cline。

为什么这个 Skill 重要

它有两个 skill，解决的是两类不同的失败。伞状的 supabase skill 覆盖全部 Supabase 产品——Database、Auth、Edge Functions、Realtime、Storage、Vectors、Cron、Queues——以及在 Next.js、React、SvelteKit、Astro、Remix 里使用的客户端库（supabase-js、@supabase/ssr）。agent 接 auth、调 CLI 和 MCP server 时，用的就是它。supabase-postgres-best-practices skill 更窄也更深：来自 Supabase 的 Postgres 性能指南，组织成按影响分级的 8 类参考——Query Performance、Connection Management、Security & RLS 都标为 Critical，Schema Design 和 Concurrency & Locking 次之。

两者都遵循标准 skill 结构——一个 SKILL.md 清单加可选的 references/ 文件——按需加载细节。

安装

全部安装：

npx skills add supabase/agent-skills

或只装一个：

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

Claude Code 用户也可以走插件 marketplace：

claude plugin marketplace add supabase/agent-skills
claude plugin install supabase@supabase-agent-skills
claude plugin install postgres-best-practices@supabase-agent-skills

详细安装说明在 Supabase 的 AI Skills 文档里。

实战：上线前审查 Schema

你要发布一个手写 migration 的新功能，想把性能和 RLS 角度过一遍。

1. 装上 best-practices skill（定向安装让 agent 的上下文保持精简）。
2. 提示 agent：

Review my schema for performance issues

3. 审查标出问题后，接着用 Help me add proper indexes to this table 逐个处理。

skill 从分级类别中取材，所以查询和连接管理会先于低影响的进阶项被检查到。

实战：在 Next.js 里接 Auth

README 的示例 prompt 覆盖了整条搭建路径：

Help me set up Supabase Auth with Next.js

伞状 skill 熟悉 @supabase/ssr 集成和 auth 的坑——sessions、JWT 处理、cookies——这些正是 agent 最容易写出"看着对其实错"的代码的地方。

技巧

• 按需安装：写应用的会话用伞状 skill，查 SQL 和动 schema 时用 Postgres skill——README 自己也建议按需挑选。
• Supabase 在 supabase.com/.well-known/agent-skills/ 发布了 discovery 索引，符合 agent-skills 的 .well-known URI 规范。
• 装好后 skill 自动触发——prompt 里不需要任何特殊前缀。
• 发布走 Release Please 自动化，每个 semver release 都会构建 skill tarball 和索引。

何时不用这个 Skill

这些指导是 Supabase 形状的。Postgres best-practices skill 围绕 Supabase 平台——连接池、RLS 约定、它的扩展——所以别处一个纯净 Postgres 项目会觉得部分内容不适用。如果你完全不用 Supabase，通用的 Postgres skill 更合适。

查看 排行榜 了解更多 skill。