Name: postgres
Rating: 71.2 (1 reviews)
Author: timescale

postgres

Use this skill for any PostgreSQL database work — table design, indexing, data types, constraints, extensions (pgvector, PostGIS, TimescaleDB), search, and migrations. **Trigger when user asks to:** - Design or modify PostgreSQL tables, schemas, or data models - Choose data types, constraints, indexes, or partitioning strategies - Work with pgvector embeddings, semantic search, or RAG - Set up full-text search, hybrid search, or BM25 ranking - Use PostGIS for spatial/geographic data - Set up TimescaleDB hypertables for time-series data - Migrate tables to hypertables or evaluate migration candidates - Plan or execute safe schema migrations with zero downtime **Keywords:** PostgreSQL, Postgres, SQL, schema, table design, indexes, constraints, pgvector, PostGIS, TimescaleDB, hypertable, semantic search, hybrid search, BM25, time-series, migration

Quality

88%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

80%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

An effective, well-organized reference hub: lean, clearly navigable, with one-level-deep references and per-reference triggers. Its main weakness is that the top-level workflow lacks an explicit validation/verification checkpoint for the destructive migration operations it dispatches, which caps workflow clarity.

Suggestions

Add an explicit validation step to the 'How to Use' workflow (e.g., 'After any migration or DDL change, validate results against expected state and confirm rollback readiness before proceeding') to satisfy the destructive-operation feedback-loop expectation.

Surface the sub-skill references that currently sit one level deeper (e.g., backfill-strategies, validation-queries, complete-example) from within the migration reference's own index rather than leaving them discoverable only by file listing.

Consider including one small inline SQL example or command per category so the body is actionable without always requiring a reference load for simple cases.

Dimension	Reasoning	Score
Conciseness	The body is a lean ~28-line hub: no concept explanations Claude already knows, no padding — each reference gets a one-line topic summary plus a 'Use when...' trigger, and every token earns its place. The single orienting intro sentence is justified for a dispatcher skill.	5 / 5
Actionability	Navigation guidance is concrete and executable — specific file paths like 'references/pgvector-semantic-search.md' with clear 'Use for embeddings, RAG, or semantic search' triggers — so Claude knows exactly which file to load; the body intentionally defers SQL/code to the references (a legitimate instruction-only hub), leaving only minor gaps versus fully copy-paste-ready content.	4 / 5
Workflow Clarity	The 'How to Use' steps give a clear 3-step sequence (identify reference, load it, load multiple for multi-area tasks), but the workflow has no validation/verification checkpoint; because this skill covers destructive/batch production operations (schema migrations, hypertable migration, DDL changes), the missing validation cap applies and holds this at 3.	3 / 5
Progressive Disclosure	A clear overview organized into categories (Table Design, Search, TimescaleDB, Migrations) with well-signaled one-level-deep markdown links and 'Use when...' triggers; all 8 referenced files exist in ./references/, and the 3 additional bundle files belong to a sub-skill's own reference layer, so content is appropriately split and easy to navigate.	5 / 5
	Total	17 / 20 Passed

Description

96%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, well-constructed description: explicit trigger guidance, comprehensive concrete actions, natural keywords with synonyms, and a clear Postgres niche. The only soft spot is the breadth of 'any PostgreSQL database work', which carries minor overlap risk with potential single-extension skills.

Dimension	Reasoning	Score
Specificity	Lists many concrete actions across the domain — 'table design, indexing, data types, constraints, extensions (pgvector, PostGIS, TimescaleDB), search, and migrations' — plus eight specific trigger bullets (e.g., 'Set up TimescaleDB hypertables for time-series data', 'Plan or execute safe schema migrations with zero downtime'), giving comprehensive coverage rather than just several actions.	5 / 5
Completeness	Explicitly answers both 'what' ('any PostgreSQL database work — table design, indexing...') and 'when' via a labeled 'Trigger when user asks to:' block with concrete trigger phrases, matching the anchor that requires both with concrete triggers.	5 / 5
Trigger Term Quality	Natural terms users would say are comprehensively covered with synonyms (PostgreSQL/Postgres, semantic search/RAG) plus domain keywords like 'pgvector', 'hypertable', 'BM25', 'PostGIS', 'time-series', 'migration' in both the trigger bullets and an explicit Keywords line.	5 / 5
Distinctiveness Conflict Risk	The named extensions (pgvector, PostGIS, TimescaleDB) carve a clear niche, but the very broad scope 'any PostgreSQL database work' creates minor overlap risk with closely related dedicated skills (e.g., a standalone pgvector or PostGIS skill), fitting 'mostly distinct; minor overlap risk' better than a clean 5.	4 / 5
	Total	19 / 20 Passed

Validation

93%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning

	Total	15 / 16 Passed

Repository: timescale/pg-aiguide
Path: skills/postgres/SKILL.md
Commit: 2bf9f11

Reviewed: 3 days ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.