1. 基本信息
项目自述名称：所在仓库自述为「Supabase Agent Skills」（Supabase 官方出品的 AI Agent 技能合集）；本技能自身 SKILL.md 标题为「Supabase Postgres Best Practices」，官方博客称其为该合集的“旗舰技能”。
| 项目 | 内容 | 数据来源 |
|---|---|---|
| 名称 | supabase-postgres-best-practices-supabase-agent-skills | — |
| 作者/维护者 | Supabase 官方团队（主要维护者 Rodriguespn，具名外部贡献者含 Dev-iL、tomaspozo 等） | GitHub API（commits）+ LICENSE 文件 |
| 来源链接 | https://github.com/supabase/agent-skills/tree/main/skills/supabase-postgres-best-practices | — |
| 许可证 | MIT | GitHub API |
| GitHub Stars / Forks | 所属仓库 2,441★ / 177 forks（该数字属整个 agent-skills 合集，不代表本技能个体热度；本技能子目录自身自 2026-01 起持续有独立提交） | GitHub API |
| 最新版本 | v0.1.6（发布于 2026-07-10） | GitHub Releases |
| 安装方式 | npx skills add 跨 Agent 安装，或 Claude Code 插件市场（见第 10 章） |
仓库 README |
2. 功能介绍与亮点
supabase-postgres-best-practices 是 Supabase（广受欢迎的开源 Firebase 替代品、Postgres 云托管平台）官方维护的 Postgres 性能与安全最佳实践参考手册，把团队多年支撑海量生产数据库积累的调优经验固化成 30 条规则，供 AI 编程助手在写查询、设计表结构、配置连接池时直接引用，而不是依赖模型自身可能过时的训练记忆。
核心亮点：
- 体系化覆盖 8 大类别：按影响力从高到低排列查询性能、连接管理、安全与 RLS、模式设计、并发与锁定、数据访问模式、监控诊断、高级特性，每类规则有独立前缀（如
query-、security-）便于检索。 - 每条规则配对照示例：30 余篇参考文档逐条给出错误写法与正确写法的 SQL 对比，部分附带
EXPLAIN执行计划或具体性能指标，而非空泛建议。 - 官方专文发布：Supabase 官方博客发表专门文章介绍这一技能，明确其定位为合集中的“旗舰技能”。
.well-known标准化分发：每次发版会同步生成符合 Agent Skills 开放标准的.well-known/agent-skills索引，供 supabase.com 与第三方工具程序化发现。- 持续迭代：最新版本发布于 2026-07-10，仓库内有超过 20 个由真实用户提交的具体技术反馈 issue（详见第 8 章），说明该技能被实际用于生产项目而非停留在演示阶段。
3. 适用场景
固定分类：数据分析与可视化。
面向任何需要编写、审查或优化 Postgres 相关代码的开发者：设计新表结构与索引策略、排查慢查询、配置连接池与并发控制、审计 Row-Level Security 策略，尤其适合使用 Supabase 或自建 Postgres、希望 AI 助手给出的建议有据可依而非凭空生成的团队。
4. 跨 Agent 兼容性
- Claude Code：✅ 原生支持，README 提供插件市场安装命令（
claude plugin marketplace add supabase/agent-skills）与npx skills add两种路径。 - Codex：✅ 原生支持——安装依赖的
npx skills add命令由 vercel-labs/skills 包提供，其官方 Supported Agents 表格明确列出 Codex（--agent codex，安装至~/.codex/skills/）。 - OpenClaw：✅ 原生支持——同一 vercel-labs/skills 表格列出 OpenClaw（
--agent openclaw，安装至~/.openclaw/skills/）。 - Hermes Agent：✅ 原生支持——同表格列出 Hermes Agent（
--agent hermes-agent，安装至~/.hermes/skills/）。
（结论基于已抓取的仓库 README 与其指定安装工具 vercel-labs/skills 的官方文档核实，未为兼容性单独发起额外搜索。）
5. 推荐理由
由 Supabase 官方基于真实生产经验整理成 30 条可对照执行的 Postgres 规则，覆盖查询、连接、安全、模式设计全流程，让 AI 助手写出的数据库代码有权威依据而非凭训练记忆臆测，且已在真实项目中被大量使用并持续收到具体的技术反馈。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 8 | 所属仓库为合集仓库，其 2,441★ 不计入本技能个体热度；但 Supabase 官方博客为本技能单独发文推介，且仓库中有超过 20 位不同真实用户就本技能内容提交具体、详细的技术反馈 issue（涉及具体文件与规则条目），核查样本账号创建时间跨度大（2012–2024）、活动记录真实，非刷量迹象 |
| 可用性 | 8 | 一条命令（npx skills add）或插件市场即可安装；文档体系完整（30 余篇分主题参考文档配 SQL 对照示例）；最近一次发版为 2026-07-10，维护活跃；无需任何付费依赖；但用户反馈中存在文档索引不完整、个别场景下技能未能可靠触发等已知问题（详见第 11 章），故不打满分 |
| 安全性 | 9 | 技能全部内容为 37 个纯 Markdown 参考文档，逐一核对未发现任何 shell 命令执行、网络请求或可疑指令；License 明确为 MIT，作者为可查证的官方团队 |
安全检查清单：
- ① 是否执行 shell 命令及权限范围：否，技能仅作为参考文档指导 AI 生成 SQL 代码，本身不执行任何命令
- ② 运行时是否联网外发数据：否，纯本地静态文档，无运行时网络调用
- ③ 是否要求 API key/凭据：否
- ④ SKILL.md 与附带文档中有无可疑指令：未发现任何 prompt injection 迹象或混淆内容
- ⑤ 作者/组织信誉：Supabase 官方团队，具名维护者可查，公司信誉良好
- ⑥ License 是否明确：明确，MIT
- ⑦ 最近维护时间：本技能子目录最近一次发版提交为 2026-07-10，在近 3 个月内
7. 跟同类 Skills 相比的优势
| 对比对象 | 定位 | 与本技能的差异 |
|---|---|---|
| neon-postgres（Neon 官方） | 聚焦 Neon Serverless Postgres 平台自身特性——分支、自动伸缩、缩容至零、只读副本、连接池配置 | 讲的是“如何用好 Neon 这个托管平台”，非通用查询/模式性能调优；本技能不绑定任何托管商，专注 Postgres 本身的查询、索引、锁与安全规则，适用于任何部署环境 |
| postgres（Timescale pg-aiguide） | 覆盖表设计、数据类型、pgvector/PostGIS/TimescaleDB 扩展、全文与向量检索、迁移到 hypertable | 定位偏“如何搭建”（选型、扩展、迁移路径），本技能定位偏“如何调优与审查已有代码”（索引缺失、连接泄漏、锁等待、RLS 性能陷阱等具体问题模式），二者可互补而非替代 |
| infra-postgres（ClickHouse 官方） | 服务 ClickHouse Cloud 托管 Postgres（Beta 功能）的专属场景，本地 Docker 与云端部署指引 | 受众窄，仅服务 ClickHouse 生态内的 Postgres 附加功能；本技能面向所有 Postgres 使用者的通用性能与安全规则，不绑定特定云服务 |
8. 用户评价
- zogcorp（GitHub，来源：仓库 issue #83）：“Adopted the supabase-postgres-best-practices skill bundle into a project today. CodeRabbit ran a thorough review on the bundle as part of the PR that vendored it and surfaced 13 correctness issues across the reference docs.”——反映该技能已被引入真实项目代码库并接受代码审查工具的检验。
- JesseVent（GitHub，来源：仓库 issue #100）实测对比：在未加载本技能的 claude-haiku-4.5 上进行从零搭建（greenfield）任务，模型给出的基础设计决策（主键类型、数据类型、连接模式等）存在过时训练数据导致的常见错误，以此说明该技能对基础决策质量的实际影响。
- NerdBase-by-Stark（GitHub，来源：仓库 issue #50）指出 SKILL.md 未提供完整的规则文件索引，AI 助手需要自行猜测文件名或列出目录才能找到具体规则，属已知的文档可发现性问题。
9. 其他补充
仓库每次发版会自动生成符合 Agent Skills 开放标准 .well-known 规范的索引文件，供 supabase.com 官网与其他第三方工具程序化抓取展示；同一仓库内还包含姊妹技能 supabase（覆盖 Supabase 全产品线开发场景）。
10. 安装使用方式
方式一：跨 Agent 通用安装（npx skills add）
npx skills add supabase/agent-skills --skill supabase-postgres-best-practices方式二：Claude Code 插件市场
claude plugin marketplace add supabase/agent-skills
claude plugin install postgres-best-practices@supabase-agent-skills安装后无需重启，在编写 SQL 查询、设计表结构或排查数据库性能问题时提出相关需求（如“帮我优化这条查询”或“审查这个表结构的索引设计”）即可自动触发该技能。
11. 注意事项
- 该技能是静态参考文档而非自动化诊断工具，不会主动连接数据库或执行 SQL，需要开发者或 Agent 主动应用其中的规则建议。
- 已有用户报告在部分从零搭建（greenfield scaffolding）场景下技能未能可靠触发；也有具体规则条目（如 VACUUM 语义描述、监控查询写法）被用户指出存在措辞不够精确之处，相关反馈截至目前仍为开放（open）状态，尚未全部修复。
- SKILL.md 本身未提供 31 篇参考文档的完整索引列表，依赖分类前缀检索，个别场景下可能需要 Agent 额外列出目录才能定位到具体规则文件。