Supabase Agent Skills

为开发者使用 Supabase AI Agent 提供辅助的 Agent Skills。Agent Skills 是一系列包含指令、脚本和资源的文件夹，Agent 可以发现并使用这些资源，从而更准确、高效地完成任务。兼容包括 Claude Code、GitHub Copilot、Cursor、Cline 等在内的 18 种以上的 AI Agent。

此仓库中的技能遵循 Agent Skills 格式。

安装

详细的安装说明请参阅 Supabase AI Skills 文档。

安装所有技能

npx skills add supabase/agent-skills

安装特定技能

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

Claude Code 插件

你也可以将这些技能作为 Claude Code 插件进行安装：

# 1. 安装 supabase/agent-skill 市场
claude plugin marketplace add supabase/agent-skills

# 2. 安装你需要的插件
claude plugin install supabase@supabase-agent-skills
claude plugin install postgres-best-practices@supabase-agent-skills

可用技能

supabase

涵盖所有 Supabase 产品和集成的综合性 Supabase 开发技能。

适用场景：

• 使用任何 Supabase 产品（Database、Auth、Edge Functions、Realtime、Storage、Vectors、Cron、Queues）
• 在 Next.js、React、SvelteKit、Astro、Remix 中使用客户端库和 SSR 集成（supabase-js, @supabase/ssr）
• 排查 Auth 问题（登录、登出、会话、JWT、Cookies、getSession、getUser、getClaims、RLS）
• 使用 Supabase CLI 或 MCP Server
• 处理模式（schema）变更、迁移、安全审计或 Postgres 扩展（pg_graphql, pg_cron, pg_vector）

supabase-postgres-best-practices

来自 Supabase 的 Postgres 性能优化指南。包含 8 个类别的参考资料，按影响程度排序。

适用场景：

• 编写 SQL 查询或设计模式
• 实现索引或查询优化
• 审查数据库性能问题
• 配置连接池或扩容
• 使用行级安全性（Row-Level Security, RLS）

涵盖类别：

• 查询性能（关键）
• 连接管理（关键）
• 模式设计（高）
• 并发与锁定（中高）
• 安全与 RLS（关键）
• 数据访问模式（中）
• 监控与诊断（中低）
• 高级功能（低）

使用方法

技能一旦安装，即可自动生效。当 Agent 检测到相关任务时，会自动调用这些技能。

示例：

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

技能结构

每个技能都遵循 Agent Skills 开放标准：

• SKILL.md - 必需的技能清单，包含 Frontmatter（名称、描述、元数据）
• references/ -（可选）用于详细文档的参考文件

.well-known 发现机制

每次发布时，都会在技能压缩包旁上传一个 dist/index.json。此索引符合 agent-skills .well-known URI 规范（架构版本 v0.2.0），并被 supabase.com 使用，以在 https://supabase.com/.well-known/agent-skills/ 提供技能服务。

发布工件由 scripts/build-release.ts 构建，并由 Release Please 在每次语义化版本（semver）发布时触发。

迁移至官方 GitHub Action

jonathanhefner/agentskills-build-for-well-known 旨在转移到 agentskills 组织并发布到 GitHub Marketplace。届时，scripts/build-release.ts 和 release-please.yml 中的 pnpm build:release 步骤可以直接替换为该 Action：

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

其他所有部分——如 Release Please 触发器、上传步骤、supabase-plugin 分发——保持不变。该脚本与 Action 产生的输出完全一致，因此可以直接无缝替换。