前言¶

慢查询、缺索引、连接数打满，这类问题往往要在文档、EXPLAIN 输出和运维经验之间来回翻。把 Agent 拉进排查时，如果缺少一套稳定的 PostgreSQL 优化指引，回答容易散、SQL 示例也不一致。

下面介绍 SkillHub 上的 Postgres优化（坐标 @user_3c6cb52e/postgres-optimization-sh-g3z1h6，版本 1.0.0）。它以通用 SKILL.md 形式发布，安装后 Agent 可按技能内整理的索引、执行计划、分区与连接池等要点协助你完成 Postgres 相关任务。

这是什么¶

Postgres优化 是面向 AI Agent 的 PostgreSQL 优化专用技能，官方简介为：帮助 Agent 高效完成相关任务。

• 来源：SkillHub community 技能，发布者 user_3c6cb52e
• 分类：dev-programming（技能元数据中还标注「开发者工具」）
• 许可：MIT（见技能包内 SKILL.md 头部）
• 依赖：标签 requires_api_key=false，无需额外 API Key
• 适配框架（技能元数据列出）：Claude Code、Codex、Hermes Agent、OpenClaw、QClaw、WorkBuddy 等；Cursor 等客户端可通过 SkillHub CLI 安装到各自 skills 目录使用

技能主页与 API 入口：

• 页面：https://www.skillhub.cn/skills/user_3c6cb52e/postgres-optimization-sh-g3z1h6
• API：https://api.skillhub.cn/user_3c6cb52e/postgres-optimization-sh-g3z1h6

截至资料抓取时，SkillHub 显示评分 100000、下载 1460 次（安装计数为 0，以页面统计为准）。

核心功能¶

技能正文以 PostgreSQL Optimization 为主题，把常见优化工作拆成可引用的片段与清单，主要包括：

1. 索引策略：B-tree、复合索引列顺序、部分索引、覆盖索引（INCLUDE）、GIN（JSONB）、GiST（全文）、CREATE INDEX CONCURRENTLY 等示例 SQL。
2. 读懂执行计划：EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT) 示例，并说明应关注的计划节点（如 Seq Scan、Nested Loop、Sort、缓冲区 hit/read）。
3. 表分区：按 RANGE 分区建表与子分区示例；建议在按分区键过滤且行数超过约 1000 万 时考虑分区。
4. JSONB： containment（@>）、嵌套字段查询与更新、jsonb_array_elements_text 等操作示例。
5. 连接池：pgbouncer.ini 片段（transaction 池模式、连接数等），并区分 transaction 级与 session 级池的适用场景。
6. 常用诊断 SQL：基于 pg_stat_statements 查慢查询、基于 pg_stat_user_indexes 找未使用索引。
7. 反模式与检查清单：例如盲目建索引、不写 EXPLAIN ANALYZE、高峰跑 VACUUM FULL 等；附带优化项勾选清单（pg_stat_statements、复合索引顺序、PgBouncer/pgcat 等）。

以上能力均来自技能包内 SKILL.md，不包含独立可执行脚本；Agent 主要是在对话与改 SQL/配置时对齐这些约定与示例。

安装与启用¶

1、安装 SkillHub CLI¶

先确认本机是否已有 CLI：

command -v skillhub && skillhub --version

若未安装，可按 SkillHub 官方安装文档执行完整安装（CLI + 默认 Skill）：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash

仅安装 CLI 时：

curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only

2、安装 Postgres优化 技能¶

安装时必须用 --dir 指向当前 Agent 的 skills 目录，否则默认落在 ./skills/，Agent 可能无法加载。

skillhub install '@user_3c6cb52e/postgres-optimization-sh-g3z1h6' --dir <skills 目录>

常见客户端 skills 路径（摘自 SkillHub 安装文档）：

• Cursor：~/.cursor/skills/
• Claude Code：~/.claude/skills/
• Codex：~/.codex/skills/ 或项目下的 .agents/skills/

也可将官方页面给出的提示词发给 Agent，让其按 https://skillhub.cn/install/skillhub.md 完成安装：

请根据 https://skillhub.cn/install/skillhub.md，安装 `@user_3c6cb52e/postgres-optimization-sh-g3z1h6`。

安装完成后，按你所用客户端的要求重启或刷新 Agent，使技能生效。

典型用法¶

技能不提供单独 CLI；典型流程是：安装技能 → 在对话中描述库表与慢查询现象 → 让 Agent 按技能中的模式给出索引、计划解读或配置建议。

下面两段来自技能正文，可直接作为与 Agent 对齐的复现起点。

用 EXPLAIN 分析关键查询（Agent 可据此讲解计划里是否出现全表扫描、排序是否未走索引等）：

EXPLAIN (ANALYZE, BUFFERS, FORMAT TEXT)
SELECT o.id, o.total, u.name
FROM orders o
JOIN users u ON o.user_id = u.id
WHERE o.status = 'shipped'
  AND o.created_at > NOW() - INTERVAL '30 days'
ORDER BY o.created_at DESC
LIMIT 20;

为高频过滤条件建部分索引：

CREATE INDEX idx_orders_pending ON orders (created_at)
  WHERE status = 'pending';

你还可以让 Agent 对照技能末尾的 Checklist（pg_stat_statements、复合索引列顺序、连接池、分区与无用索引等）逐项核对当前环境。

适用场景与注意¶

适合谁

• 日常用 PostgreSQL，需要 Agent 在索引设计、EXPLAIN 解读、JSONB 查询、PgBouncer 配置等方面给出与文档一致的建议。
• 已在 Cursor、Claude Code、Codex 或 OpenClaw 系客户端中使用 Skills，希望把 Postgres 优化知识固化成可复用提示词包。

限制与注意

• 技能内容是知识与 SQL/配置模板，不会自动连接你的数据库；生产变更仍需你在目标环境验证，并在低峰期执行 CREATE INDEX CONCURRENTLY 等操作。
• 元数据中的 homepage / repository 指向 GitHub 用户页，与 SkillHub 包版本 1.0.0 的维护关系以 SkillHub 发布为准；升级可用 skillhub 在对应 skills 目录内更新（遵循 https://skillhub.cn/install/skillhub.md 的说明）。
• 分区、池化参数等需结合实际数据量与访问模式；技能内给出的阈值（例如约 1000 万行考虑分区）是经验性提示，不是硬性规则。

结尾¶

Postgres优化 把索引、执行计划、分区、JSONB、连接池和诊断 SQL 收进一份 SKILL.md，让 Agent 在 Postgres 相关任务上有统一参照。若你使用 SkillHub 管理技能，可从官方页面安装：

https://www.skillhub.cn/skills/user_3c6cb52e/postgres-optimization-sh-g3z1h6