概述

火山引擎 Supabase Skill 用于让 AI Agent 通过 byted-supabase-cli 管理 AI 原生 BaaS 平台 Supabase 版资源。本文说明 Skill 的定位、安装、配置、使用方式和常见问题。

该 Skill 服务的是火山引擎 Supabase，不是官方开源 Supabase CLI，也不是官方 Supabase 云服务的完整替代品。平台沿用 Supabase 生态中的 PostgreSQL、Auth、Realtime、Storage、Edge Functions、REST Data API 等能力，同时使用火山引擎的资源和鉴权模型。

资源层级主要包括 Workspace、Branch 和 Compute。

云端管理统一通过 byted-supabase-cli 完成。

云端鉴权使用火山引擎账号、OAuth 登录或 AK/SK 凭据。

部分命令、参数、迁移方式和官方 supabase CLI 不同，不能直接套用官方 Supabase CLI 的命令习惯。

核心能力

该 Skill 适用于涉及 AI 原生 BaaS 平台 Supabase 版的资源管理、开发、部署、安全配置和问题排查任务。

管理火山引擎 Supabase 的 Workspace、项目、Branch、Compute 和访问端点。

创建、查看、配置、启动、停止或删除 Supabase Workspace。

管理 Branch、默认 Branch、Branch 恢复或 Branch 计算资源。

执行 SQL 查询或数据库 Schema 变更。

创建表、索引、视图、函数、触发器、扩展或声明式 Schema。

配置 Auth、用户、会话、JWT、认证提供方或授权。

配置 Realtime 订阅和数据库变更通知。

开发、部署、列出、下载或删除 Edge Functions。

创建、查看、配置或删除 Storage 存储桶，上传、下载、移动、列出或删除 Storage 对象。

部署前端静态站点，并将其绑定到已有的 Supabase Workspace。

获取 API Key、连接字符串、端点信息或项目配置。

根据 Supabase 数据库 Schema 生成 TypeScript 类型。

设计或评审 RLS 策略、Storage 策略、数据库权限或 Supabase 安全配置。

通过 Supabase SDK 将 Supabase 集成到应用中。

调试权限错误、SQL 错误、Schema 访问问题、RLS 行为、Edge Function 失败、Storage 失败或其他异常行为。

排查 IAM 授权、CLI 配置、地域、Workspace、Branch 和部署相关问题。

使用火山引擎 Supabase CLI 或 MCP Server 查看或管理平台资源。

Skill 安装完成后，AI Agent 仍会遵守 CLI 的参数校验、权限校验和服务端返回结果。Skill 不会绕过登录，也不会扩大当前账号权限。如需配置工具调用，请参见火山引擎 Supabase MCP Server 用户指南。

适用范围

以下请求适合使用该 Skill

创建、查看、重命名、暂停、恢复或删除火山引擎 Supabase Workspace。

管理 Workspace 的 Branch、默认 Branch、Branch 恢复和 Branch 算力。

执行 SQL、变更表结构、查看扩展、迁移和数据库运行状态。

生成 TypeScript、Go 或 Swift 数据库类型。

配置 Supabase Auth、Auth Hooks 和第三方 JWT/OIDC 提供方。

管理 Realtime 和应用侧 Supabase SDK 接入。

创建、部署、下载和删除 Edge Functions。

创建、配置、上传、下载和删除 Storage Bucket 或对象。

部署 IGA Pages 静态站点并绑定 Supabase Branch。

获取访问地址、连接串、API Key 和环境变量。

做数据库安全、性能、RLS、索引、锁和连接方面的检查。

根据 CLI 返回的错误进行定位和恢复。

以下请求通常不需要使用该 Skill

只讨论 PostgreSQL 或 Supabase 的通用概念，不操作火山平台实例。

操作 RDS MySQL、Redis 或其他非 Supabase 产品。

只编写与 Supabase 后端无关的前端页面。

只询问概念或文档，不需要读取云端实时状态。

使用官方 Supabase CLI 的本地容器、官方迁移工作流或其他未在本平台注册的命令。

前提条件

安装和使用 Skill 前，请确认已经满足以下条件：

已有可访问 AI 原生 BaaS 平台 Supabase 版资源的火山引擎账号。

账号具备目标 Workspace、Branch、数据库、Storage、Edge Functions 或 Pages 资源的读取或管理权限。

本地已安装 Node.js，并且 npm 和 npx 可用。

当前 AI Agent 支持加载 Skill，例如 Trae Work、Trae Code、Claude Code、Codex、Coze 或 ArkClaw。

如需让 Agent 直接调用工具，需要按对应工具要求配置 MCP Server。详情请参见火山引擎 Supabase MCP Server 用户指南。

网络环境可以访问 npm Registry、GitHub 或所选 Skill 市场。

安全须知：不要把 AK、SK、Session Token、数据库密码或 service_role Key 写入仓库、前端代码、公开日志或聊天记录。service_role Key 具备高权限，只应在可信服务端环境中使用。进行查询、演示或排障时，优先使用只读模式或只读账号。

安装

智能安装

可以将下面的提示词复制给 AI 助手，例如 Claude Code、Codex、Cursor 或 Trae Code，让 Agent 自动安装火山引擎 Supabase CLI 和 Skill。

手动安装

推荐使用引导安装。该命令会安装 CLI、准备平台相关的原生二进制缓存，并同步匹配版本的 Skill。

安装流程包括：

全局安装 @byted-supabase/cli@latest。

准备当前操作系统和 CPU 架构对应的原生 CLI。

执行 byted-supabase-cli skills install。

将 byted-supabase Skill 全局同步到 AI Agent。

在 ~/.supabase/skills-state.json 中记录 Skill 的版本和来源。

如果只需要分步安装 CLI 和 Skill，可以先安装 CLI：

然后单独安装 Skill：

Skill 的默认安装方式是全局安装，不随项目目录保存。首次安装或更新 Skill 需要 Node.js、npm 和 npx 可用。

按工具安装或接入

Trae Work

Trae Work 插件市场已预装火山引擎 Supabase Skill 插件，可在执行任务时指定该 Skill。

Trae Code

在 Trae Code 中完成 Skill 安装后，刷新 Skill 或重启 Agent 会话。可以在对话框中输入以下内容进行验证：

如果需要在 Trae Code 中发现并调用 CLI 工具，请在 Trae Code 的 MCP 设置中完成配置，详情请参见火山引擎 Supabase MCP Server 用户指南。

Coze

Skill 已上架 Coze 技能商店，可通过该分享链接使用：Coze 技能商店中的 byted-supabase-skill。

ArkClaw

在 ArkClaw 中有多种安装方式，可选择其中一种。

方式一：通过 Zip 包安装。向 ArkClaw 发送以下指令，由 ArkClaw 下载并安装：

方式二：通过 GitHub 安装。 Git 不能直接克隆仓库中的子目录。可以先克隆仓库，再复制 Skill 目录到 ArkClaw 的 Skill 目录。

方式三：通过 ClawHub 安装。访问 ClawHub 上的 Supabase Skill 页面，下载 Zip 压缩包，并解压到 ~/.openclaw/skills 目录。

方式四：通过 Find Skill 安装。访问 Find Skill 上的 Supabase Skill 页面，下载 Zip 压缩包，并解压到 ~/.openclaw/skills 目录。

Claude Code

完成 Skill 安装后，重新打开会话或刷新 Skill 列表，然后输入：

如果需要让 Claude Code 直接调用 CLI 工具，请继续参考火山引擎 Supabase MCP Server 用户指南配置 MCP。

Codex

在 Codex 中完成 Skill 安装后，重新启动会话，让 Codex 加载最新 Skill。可以使用以下提示词验证：

需要执行 CLI 工具调用时，请按 Codex 当前支持的 MCP 配置方式添加服务，具体配置请参见火山引擎 Supabase MCP Server 用户指南。

VS Code

在 VS Code 中完成 Skill 安装后，重新打开 Agent 会话。在对话框中输入：

如果 VS Code 需要通过工具直接调用 CLI，请在 VS Code 的 MCP 设置中配置 byted-supabase-cli mcp serve，详情请参见火山引擎 Supabase MCP Server 用户指南。

配置

浏览器登录

推荐使用浏览器 OAuth 登录：

登录后的凭据和 Profile 由 CLI 管理，后续命令通常不需要重复输入凭据。省略地域时默认使用 cn-beijing。

AK/SK 配置

也可以配置 AK/SK：

查看配置：

CLI 配置文件通常位于：

注意请不要把该配置文件、AK、SK、Session Token 或 service_role Key 提交到代码仓库或发送给前端。生产环境建议使用最小权限账号，并按需开启只读模式或人工确认机制。

Skill 调用方式

安装完成后，AI Agent 会自动发现 Skill。用户可以直接描述需求，例如：

AI Agent 应先读取 Skill 规则，再调用 CLI 查询；不应凭记忆猜测命令、资源 ID 或参数。

支持显式指定 Skill 的 Agent 可以使用：

Skill 的名称是 byted-supabase，不是 supabase，也不是 byted-supabase-cli。

安装位置和状态文件

常见 Skill 目录如下：

AI Agent	常见 Skill 目录
Trae	~/.trae/skills/byted-supabase
Codex	~/.codex/skills/byted-supabase
Claude Code	~/.claude/skills/byted-supabase

不同版本的 Agent、操作系统或安装配置可能使用不同目录。可以使用以下命令查看本机已安装的全局 Skill：

如需确认某个 Agent 的目录，可以查看对应通用路径：

部分 Agent 目录可能是指向共享 Skill 目录的软链接，这是正常现象。

以下文件不是 Skill 正文目录，而是 CLI 用于版本同步检查的状态文件：

该文件记录 Skill 名称、来源地址、最后一次同步时对应的 CLI 版本和最后同步时间。不要把 ~/.supabase/skills-state.json 当作 Skill 内容目录，也不要手工修改它来伪造安装状态。

使用

安装 Skill 后，可以直接向 AI Agent 提出自然语言需求。以下示例均来自原文。

快速登录

查询项目

查询详情

执行查询

创建表

部署页面

安装检查

查看 Skill 安装状态：

状态可能表示：

not installed：没有成功记录过 Skill 安装。

installed：已经安装，但当前构建无法比较版本。

in sync：Skill 与当前 CLI 版本匹配。

out of date：Skill 是旧版本，需要同步。

普通同步发现版本一致时会跳过重复安装。需要重新拉取 Skill 时使用：

执行 byted-supabase-cli update 时，CLI 会尝试同步与当前版本匹配的 Skill。普通 CLI 命令启动后也会做本地、无网络的版本漂移检查；如果发现 Skill 版本落后，会提示执行：

常见问题与故障排查

为什么 Skill 没有安装成功？

检查 Node.js、npm 和网络连接，然后执行：

为什么 Skill 显示过期？

执行以下命令重新同步：

Skill 安装后为什么 Agent 仍不能调用工具？

Skill 只负责提供操作说明，工具调用还需要配置 MCP。请参见火山引擎 Supabase MCP Server 用户指南，完成对应工具的 MCP 配置。

如何查看 CLI 的真实命令？

以当前 CLI 的帮助输出为准：

Skill 安装和同步命令有哪些？

命令	作用
byted-supabase-cli skills install	安装或同步当前 CLI 对应版本的 Skill。
byted-supabase-cli skills install --force	忽略同步状态，强制重新安装。
byted-supabase-cli skills install --json	输出结构化安装结果。
byted-supabase-cli skills status	查看安装和版本同步状态。
byted-supabase-cli skills status --json	输出结构化状态。
byted-supabase-cli skills update	install 的兼容别名。
byted-supabase-cli skills sync	install 的兼容别名。