前言¶
用 Cursor、Claude Code 或 Copilot 接 Supabase 时，常见问题不是「会不会写 SQL」，而是上下文不对：RLS 策略漏了 WITH CHECK、把 user_metadata 写进授权逻辑、新表没暴露到 Data API，或者还在用已废弃的 auth.role()。模型训练数据往往落后于 Supabase 文档和 changelog，同一套提示词很难覆盖 Database、Auth、Edge Functions、Realtime、Storage 等整条产品线。
下面介绍 Supabase 在 agent-skills 仓库里维护的 supabase Skill（当前 manifest 版本 0.1.2，作者 supabase）。它把「先查 changelog、再查文档、改完要验证、安全清单」写成 Agent 可加载的流程说明，在涉及 Supabase 的任务里自动参与决策。
这是什么¶
supabase 是一条面向「任何 Supabase 相关任务」的综合开发 Skill，遵循 Agent Skills Open Standard：根目录有 SKILL.md（含 name、description、metadata），可选 references/ 放详细参考。
- 维护方：Supabase（官方仓库 supabase/agent-skills）。
- 兼容环境：资料写明兼容 18+ 种 AI Agent，包括 Claude Code、GitHub Copilot、Cursor、Cline 等；安装后由 Agent 在检测到相关任务时自行选用。
- 与同仓库其他 Skill 的关系：同仓还有 supabase-postgres-best-practices（侧重 Postgres 性能与 schema）；官方文档建议在做表结构、迁移、RLS、索引等数据库改动前优先加载 postgres 最佳实践 Skill。supabase 覆盖更广的产品面与排障场景，二者可配合使用。
核心功能¶
Skill 的 description 与文档列出的触发范围一致，主要包括以下几类（均来自官方 SKILL 与文档表述）。
产品线与集成¶
- 产品：Database、Auth、Edge Functions、Realtime、Storage、Vectors、Cron、Queues。
- 客户端与 SSR：
supabase-js、@supabase/ssr，以及 Next.js、React、SvelteKit、Astro、Remix 等集成。 - 平台工具：Supabase CLI、MCP server；schema 变更、migrations、declarative schemas、安全审计；Postgres 扩展（如 pg_graphql、pg_cron、pg_vector）。
Auth 与排障¶
- Auth 主题：登录/登出、session、JWT、cookies、
getSession、getUser、getClaims、RLS。 - 调试：HTTP/Postgres 错误、RLS 意外行为、permission denied、schema cache、超时、Edge Function 崩溃、Realtime 断开、Storage 失败；查阅 Logs Explorer、ClickHouse 等日志。
内置工作原则（SKILL.md Core Principles）¶
官方在 Skill 正文里固定了几条执行原则，Agent 被要求遵守：
-
变更频繁，以文档和 changelog 为准
实现前先拉取https://supabase.com/changelog.md，关注与任务相关的breaking-change，再按 Skill 内指引查阅当前文档；不要依赖模型的过时记忆。 -
改完要验证
修复或实现后应跑测试查询（或等价验证），未验证视为未完成。 -
失败不要死循环
同一思路失败 2～3 次应换方法、查文档、细看错误与日志。 -
Data API 暴露与 RLS
新表是否对 REST/Data API 可见取决于项目 Data API settings；anon/authenticated可能需要显式GRANT。这与 RLS（控制可见行）是两层问题。对暴露 schema（默认含public）的表应启用 RLS，策略要匹配真实访问模型，而不是每张表套同一套auth.uid()模板。 -
安全清单
涉及 auth、RLS、视图、Storage、用户数据时，Skill 要求逐项核对常见陷阱，例如：
- 不要用user_metadata做 JWT 授权决策，授权数据应放在app_metadata；
- 删除用户不会立即使旧 access token 失效；
- 前端禁止暴露service_role；Management API / CLI / MCP 宜用 scoped personal access token；
- 视图默认绕过 RLS（Postgres 15+ 可用security_invoker）；
- UPDATE 需要 SELECT policy；auth.role()已废弃，应使用 policy 的TO authenticated/TO anon，且仅TO authenticated不能替代行级授权；
- UPDATE policy 需要USING与WITH CHECK；
- 慎用SECURITY DEFINER，public下的 definer 函数默认可被anon/authenticated调用。
（Storage 等条目在完整 SKILL.md 中还有续篇；安装后由 Agent 加载全文。）
安装与启用¶
官方推荐通过 skills CLI 安装；默认装在项目作用域，便于贡献者与 Cloud Agent 共享同一套 Skill。需要全局安装时可加 --global；可为检测到的所有 Agent 一次性安装时加 --all。详见 Supabase AI Skills 文档。
只安装 supabase Skill¶
npx skills add supabase/agent-skills --skill supabase
安装仓库内全部 Skill¶
npx skills add supabase/agent-skills
更新¶
npx skills update
可按 Skill 名称只更新部分，例如 npx skills update supabase（以 skills 包文档为准）。
Claude Code 插件方式（可选）¶
claude plugin marketplace add supabase/agent-skills
claude plugin install supabase@supabase-agent-skills
与 MCP 的组合¶
文档提到可将 Agent Skills 与 Supabase Plugin for AI Coding Agents（含 MCP server）一起做一步配置；具体步骤以 AI Tools 文档 与 Plugin 说明为准。
安装完成后 Skill 自动可用，无需在每次对话里手动 @；Agent 根据任务描述中的 Supabase 相关意图选用。仓库还通过 release 构建 dist/index.json，由 https://supabase.com/.well-known/agent-skills/ 提供发现索引（符合 agent-skills .well-known 规范）。
典型用法¶
以下示例来自官方 README / 文档中的 Usage 说明，可直接作为自然语言任务交给已安装 Skill 的 Agent：
Help me set up Supabase Auth with Next.js
Review my schema for performance issues
（后者更贴近 supabase-postgres-best-practices；若同时安装两个 Skill，Agent 可按任务拆分加载。）
更贴合 supabase 本体的任务示例：
Debug why my RLS policy returns zero rows on UPDATE
Add Edge Function and check logs when it crashes
Expose a new SQL table to the Data API with proper GRANT and RLS
实践上，你描述产品模块（Auth、Realtime、Storage 等）、框架（如 Next.js + @supabase/ssr）和错误现象即可；Skill 会推动 Agent 先对 changelog、再对官方文档，并在安全相关改动时走清单。
适用场景与注意¶
适合谁
- 已在用或计划用 Supabase 做 BaaS（数据库 + Auth + 实时 + 存储 + Edge）的团队。
- 希望 AI 写迁移、RLS、SSR 会话代码时，默认带上 Supabase 官方安全与 API 暴露规则的场景。
- 使用 Cursor、Claude Code、Copilot 等支持 Agent Skills 的工具链的开发者。
限制与注意
- Skill 是流程与规则载体，不能替代你在 Dashboard 里的项目配置、密钥管理与生产变更评审。
- Supabase 迭代快：除 Skill 内强调的 changelog 外，应定期执行
npx skills update。 - 纯 Postgres 性能与 schema 深度优化，官方另备 supabase-postgres-best-practices；大改表结构前建议两个 Skill 一起装。
- 涉及 Management API、CLI、MCP 的自动化时，按文档使用 scoped personal access token，避免长期把全账号权限交给脚本或 Agent。
结尾¶
supabase Skill 把 Supabase 全产品线与常见踩坑（尤其是 RLS、Data API、Auth JWT）收敛成 Agent 可执行的官方话术，适合作为接 Supabase 项目时的默认上下文。安装命令与说明以 Supabase 文档为准。
