Write Better Postgres with pg-aiguide

Ask a coding agent to design a Postgres schema and you get plausible SQL with missing constraints, no indexes, and patterns from older Postgres versions. pg-aiguide — a 2k-star repo from Timescale — attacks that gap with two layers: curated, opinionated Postgres best-practice skills your agent installs locally, and an MCP server that does semantic search over the official PostgreSQL manual, scoped by version.

Why This Skill Matters

The skills directory holds eleven skills covering the whole design loop: postgres and schema-exploration in the quickstart, plus design-postgres-tables, design-postgis-tables, postgres-database-migration, postgres-hybrid-text-search, pgvector-semantic-search, and TimescaleDB-specific ones (setup-timescaledb-hypertables, timescaledb-hyperfunctions, find-hypertable-candidates, migrate-postgres-tables-to-hypertables). The README lists what the guidance covers: exploring existing schemas and objects, schema design, indexing strategies, data types, data integrity and constraints, naming conventions, performance tuning, and modern PostgreSQL features.

The MCP layer adds a search_docs tool — semantic (vector) and keyword (BM25) search in one — over three sources: the official PostgreSQL manual scoped by version, Tiger Data's documentation for TimescaleDB and its ecosystem, and PostGIS docs. A view_skill tool exposes the best-practice skills to any MCP-capable agent. Ecosystem coverage starts with TimescaleDB (docs + skills) and PostGIS (docs), with pgvector listed as coming soon.

Installation

Install the flagship best-practices skill:

npx skills add timescale/pg-aiguide --skill postgres

For investigating an existing database, install the exploration skill instead:

npx skills add timescale/pg-aiguide --skill schema-exploration

Or pick from all eleven interactively:

npx skills add timescale/pg-aiguide

The README says the skills work with Claude Code, Cursor, Codex, Gemini CLI, VS Code, and 40+ other agents. To layer documentation search on top, add the public MCP server endpoint https://mcp.tigerdata.com/docs — or skip the manual config and use the Claude Code plugin, which bundles the skills and the MCP connection:

claude plugin marketplace add timescale/pg-aiguide
claude plugin install pg@aiguide

Real Workflow: Design a Schema Under House Rules

1. Install the postgres skill and start a session.
2. Give the agent a concrete design task:

为工厂车间的 IoT 设备数据设计 Postgres 表结构：每台设备有唯一 id 和可读名称，
持续采集温度、湿度、压力等读数。要支持异常值排查和单设备历史分析。
请说明用到的约束、索引和命名规范的理由。

3. The agent works from the skill's guidance — constraints, indexing strategy, naming conventions, and modern PostgreSQL features — instead of its default habits, and explains the choices because you asked for reasons.
4. When a design question needs the official manual, the MCP search_docs tool answers from the version-scoped PostgreSQL documentation rather than the model's memory.

For an inherited database, run the schema-exploration skill first: the README scopes it to investigating existing PostgreSQL databases, which is also the safer first move before any migration task.

Tips

• Run npx skills add timescale/pg-aiguide with no flags to see all eleven skills and pick per project — the TimescaleDB set only matters if you actually run hypertables.
• The skills are explicitly opinionated; treat conflicts with your team's conventions as a review conversation, not a silent overwrite.
• The MCP server is a hosted public endpoint run by TigerData; the skills themselves are local files — pick the layer that fits your data policy.
• Codex users add the MCP server directly: codex mcp add --url "https://mcp.tigerdata.com/docs" pg-aiguide.

When Not to Use This

This is PostgreSQL-only — MySQL or SQLite projects need their own guidance. If your team already maintains internal schema standards, the opinionated defaults may collide more than they help. And the docs-search layer depends on a third-party-hosted endpoint; if policy forbids that, stay on the local skills and accept the smaller knowledge footprint.

See the leaderboard for more skills.