前言¶
用 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 文檔爲準。
