Postgres

Name: Postgres
Author: timescale

timescale/pg-aiguide

821 installs
1.8k repo stars
Updated June 26, 2026
timescale/pg-aiguide

postgres is a Claude Code skill that guides PostgreSQL schema design, indexing, extensions, search patterns, and safe migrations for developers who need production-grade Postgres without guessing data types or index stra

About

postgres is a Timescale pg-aiguide skill that routes PostgreSQL work through nine specialized reference guides covering table design, PostGIS spatial schemas, pgvector semantic search, hybrid BM25+vector search, TimescaleDB hypertables, migration scoring, zero-downtime DDL, and Ghost managed databases. The agent loads topic-specific markdown references such as design-postgres-tables.md or pgvector-semantic-search.md instead of improvising SQL. Developers reach for postgres when designing schemas, choosing indexes and constraints, setting up RAG with pgvector, configuring PostGIS or TimescaleDB, or planning production migrations. It targets PostgreSQL, pgvector, PostGIS, TimescaleDB, and Ghost CLI/MCP workflows common in SaaS and agent backends.

Routes tasks to focused references: general tables, PostGIS, Timescale hypertables, pgvector, and hybrid search
Covers data types, constraints, indexes, JSONB patterns, and partitioning strategies
Supports pgvector embeddings, semantic search, RAG, full-text, hybrid, and BM25 ranking
Guidance for PostGIS geometry vs geography, SRIDs, and spatial indexes
TimescaleDB hypertable setup and migration evaluation for time-series workloads

Postgres by the numbers

821 all-time installs (skills.sh)
+54 installs in the week ending Aug 5, 2026 (Skillselion tracking)
Ranked #101 of 911 Databases skills by installs in the Skillselion catalog
Security screen: LOW risk (skills.sh audit)
Data as of Aug 5, 2026 (Skillselion catalog sync)

npx skills add https://github.com/timescale/pg-aiguide --skill postgres

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/timescale/pg-aiguide/postgres.svg)](https://skillselion.com/skills/timescale/pg-aiguide/postgres)

Installs	821
repo stars	★ 1.8k
Security audit	3 / 3 scanners passed
Last updated	June 26, 2026
Repository	timescale/pg-aiguide ↗

How do you design PostgreSQL schemas with pgvector and TimescaleDB?

Design PostgreSQL schemas, indexes, extensions, and migrations without guessing data types or search patterns.

Who is it for?

Backend engineers building PostgreSQL-backed SaaS, analytics, RAG, geospatial, or time-series features who want opinionated reference-driven SQL instead of generic LLM guesses.

Skip if: Teams on MySQL, MongoDB, or serverless-only databases with no PostgreSQL footprint should skip postgres and use a database-specific skill instead.

When should I use this skill?

The user asks to design PostgreSQL tables, add pgvector/PostGIS/TimescaleDB, tune indexes, or plan safe schema migrations.

What you get

Schema DDL, index definitions, extension setup SQL, hybrid search queries, hypertable migration steps, and safe migration runbooks.

DDL and index SQL
Migration runbook
Search query patterns

By the numbers

Bundles 9 specialized PostgreSQL reference guides
Covers extensions including pgvector, PostGIS, and TimescaleDB

Files

SKILL.mdMarkdownGitHub ↗

PostgreSQL Expert Skills

This skill provides comprehensive PostgreSQL expertise through specialized references. Load the appropriate reference based on the task.

Available References

Table Design

[design-postgres-tables](references/design-postgres-tables.md) — Data types, constraints, indexes, JSONB patterns, partitioning, and PostgreSQL best practices. Use for any general table/schema design task.
[design-postgis-tables](references/design-postgis-tables.md) — PostGIS spatial table design: geometry vs geography types, SRIDs, spatial indexing, and location-based query patterns. Use when the task involves geographic or spatial data.

Search

[pgvector-semantic-search](references/pgvector-semantic-search.md) — Vector similarity search with pgvector: HNSW/IVFFlat indexes, halfvec storage, quantization, filtered search, and tuning. Use for embeddings, RAG, or semantic search.
[postgres-hybrid-text-search](references/postgres-hybrid-text-search.md) — Hybrid search combining BM25 keyword search with pgvector semantic search using RRF. Use when combining keyword and meaning-based search.

TimescaleDB

[setup-timescaledb-hypertables](references/setup-timescaledb-hypertables.md) — Hypertable creation, compression, retention policies, continuous aggregates, and indexes. Use when setting up TimescaleDB from scratch.
[find-hypertable-candidates](references/find-hypertable-candidates.md) — SQL queries to analyze existing tables and score them for hypertable conversion. Use when evaluating which tables to migrate.
[migrate-postgres-tables-to-hypertables](references/migrate-postgres-tables-to-hypertables.md) — Step-by-step migration: partition column selection, in-place vs blue-green, validation. Use when executing a migration.

Migrations

[postgres-database-migration](references/postgres-database-migration.md) — DDL lock reference, safe migration patterns, timeout strategies, rollback planning, and fork-based testing. Use when planning or executing schema changes on production databases.

Database Management

[ghost-database](references/ghost-database.md) — Ghost is a managed PostgreSQL service designed for AI agents. Create, fork, pause, resume, and query databases via CLI or MCP. Use when the user needs a database for agent workflows or wants to fork for safe experimentation.

How to Use

1. Identify which reference matches the user's task from the descriptions above. 2. Load the reference file to get detailed instructions and SQL patterns. 3. For tasks spanning multiple areas (e.g., "design a table with vector search"), load multiple references as needed.

Related skills

Lark BaseLet their coding agents read from, write to, and query structured data stored in Lark Base (Feishu) spreadsheets and databases.493k

Azure KustoRun fast KQL queries against Azure Data Explorer for log analytics, telemetry, and time-series data.484k1.3k

Lark SheetsCreate, read, update, and export spreadsheets inside Lark (Feishu) directly from their AI coding agent.389k15.9k

Supabase Postgres Best PracticesAutomatically apply Supabase Postgres performance rules during query writing, schema design, and database optimization.313k2.4k

Firebase Data ConnectGenerate complete, production-ready Firebase Data Connect GraphQL schemas and queries for complex relational data models.112k392

Firebase FirestoreAdd Cloud Firestore read/write capabilities to an Android Kotlin app using the official Firebase SDK.77k392

How it compares

Pick postgres when the datastore is PostgreSQL and you need extension-specific schema, search, or migration guidance rather than generic SQL snippets.

FAQ

What PostgreSQL topics does the postgres skill cover?

The postgres skill covers general table and schema design, PostGIS spatial tables, pgvector semantic search, hybrid BM25+vector search, TimescaleDB hypertables, migration candidate analysis, production-safe DDL migrations, and Ghost managed PostgreSQL for agent workflows.

When should I use postgres versus writing SQL manually?

Use the postgres skill when you need PostgreSQL-specific guidance on data types, constraints, indexes, extensions like pgvector or TimescaleDB, or zero-downtime migrations. The skill loads nine focused reference files so the agent follows tested patterns instead of generic SQL.

Is Postgres safe to install?

skills.sh reports 3 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.

Databasesbackendintegrations