design-postgres-tables

Use this skill for general PostgreSQL table design. **Trigger when user asks to:** - Design PostgreSQL tables, schemas, or data models when creating new tables and when modifying existing ones. - Choose data types, constraints, or indexes for PostgreSQL - Create user tables, order tables, reference tables, or JSONB schemas - Understand PostgreSQL best practices for normalization, constraints, or indexing - Design update-heavy, upsert-heavy, or OLTP-style tables **Keywords:** PostgreSQL schema, table design, data types, PRIMARY KEY, FOREIGN KEY, indexes, B-tree, GIN, JSONB, constraints, normalization, identity columns, partitioning, row-level security Comprehensive reference covering data types, indexing strategies, constraints, JSONB patterns, partitioning, and PostgreSQL-specific best practices.

Quality

86%

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

72%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.

A dense, highly actionable PostgreSQL design reference with excellent executable examples and concrete prescriptive guidance. Its main gaps are the absence of an explicit design workflow with validation checkpoints and no progressive disclosure into separate reference files.

Suggestions

Add a short sequenced design workflow or checklist at the top (e.g. define PK → normalize → pick types → add constraints → add indexes → consider special cases) with an explicit validation checkpoint such as testing DDL inside a transaction before applying.

Split the larger reference blocks (e.g. JSONB Guidance, Indexing, Data Types) into one-level-deep reference files under references/ and link to them from SKILL.md to improve progressive disclosure.

Remove the redundancy between the 'Do not use the following data types' section and the Data Types section by consolidating the DO/DO-NOT guidance in one place.

Dimension	Reasoning	Score
Conciseness	The body is dense and assumes Claude's competence with no padding about basic concepts, but the 'Do not use the following data types' section duplicates the Data Types section and the Extensions list repeats earlier mentions, so a few instances could be trimmed.	4 / 5
Actionability	It provides fully executable, copy-paste-ready SQL for the common cases (users, orders, JSONB profiles) plus concrete prescriptive commands and syntax for types, constraints, and indexes throughout.	5 / 5
Workflow Clarity	Sections are well-organized into an implicit design sequence (rules → gotchas → types → constraints → indexing → examples) and Safe Schema Evolution notes validation, but there is no explicit sequenced design workflow with validation checkpoints.	3 / 5
Progressive Disclosure	The file is well-structured with clear headers, but no bundle files exist and all content sits inline in a single ~200-line document with no one-level-deep references to split detailed material into.	3 / 5
	Total	15 / 20 Passed

Description

100%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 description that clearly states both what the skill does and when to trigger it, with comprehensive concrete actions and natural keywords. Third-person voice is maintained throughout with no over-claims or fluff.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — designing tables/schemas/data models, choosing data types/constraints/indexes, creating user/order/reference/JSONB tables, and designing update-heavy/upsert-heavy/OLTP tables — giving comprehensive coverage rather than vague language.	5 / 5
Completeness	It explicitly answers both 'what' ('Use this skill for general PostgreSQL table design' plus the comprehensive-reference summary) and 'when' (an explicit 'Trigger when user asks to' list with concrete trigger phrases).	5 / 5
Trigger Term Quality	The Keywords line provides comprehensive natural-term coverage with synonyms (PostgreSQL schema, table design, data types, PRIMARY KEY, FOREIGN KEY, indexes, JSONB, constraints, normalization, partitioning, row-level security) that users would actually say.	5 / 5
Distinctiveness Conflict Risk	It carves a clear PostgreSQL-table-design niche with distinct, PostgreSQL-specific triggers, so it is unlikely to fire for unrelated skills.	5 / 5
	Total	20 / 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/design-postgres-tables/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.