CtrlK
BlogDocsLog inGet started
Tessl Logo

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.

66

Quality

83%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

SKILL.md
Quality
Evals
Security

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.

An excellent, information-dense reference with copy-paste-ready SQL and precise PostgreSQL-specific guidance, weakened only by internal redundancy and the absence of any explicit design workflow or verification steps. The lack of any bundle structure means all detail is inlined in SKILL.md rather than progressively disclosed.

Suggestions

Add a short sequenced design workflow with verification checkpoints (e.g., 1. gather access patterns, 2. normalize, 3. pick types/constraints, 4. add indexes, 5. verify with EXPLAIN ANALYZE and test in a transaction with ROLLBACK) — the current body is a catalogue with no explicit process.

Split detail-heavy sections (Extensions, JSONB Guidance, the type-by-type catalogue) into one-level-deep reference files with clearly signaled pointers from SKILL.md, keeping the core rules inline.

Deduplicate the "Do not use the following data types" section against the "Data Types" and "Core Rules" sections — the same prohibitions (timestamp, char(n), money, geometric types) are stated two or three times.

DimensionReasoningScore

Conciseness

The body is dense, terse, and assumes Claude's competence — every bullet carries a concrete recommendation (e.g., "Prefer TIMESTAMPTZ for event time; NUMERIC for money", TOAST strategies with exact ALTER syntax) rather than explaining concepts. Not a 5 because there is noticeable redundancy: the "Do not use the following data types" section and parts of "Core Rules" restate guidance already given in "Data Types".

4 / 5

Actionability

Guidance is fully executable throughout: exact DDL ("BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY", "CREATE INDEX ON tbl (user_id) WHERE status = 'active'", "EXCLUDE USING gist (room_id WITH =, booking_period WITH &&)"), three complete copy-paste CREATE TABLE examples, and concrete query patterns for JSONB indexing. Specific examples cover the common cases (users, orders, JSONB profiles).

5 / 5

Workflow Clarity

The content is a well-organized reference catalogue, but there is no explicit design workflow — no sequenced steps (e.g., requirements → access patterns → normalize → types → constraints → indexes) and no verification checkpoints such as using EXPLAIN to confirm index usage. Safe-testing guidance exists ("BEGIN; ALTER TABLE...; ROLLBACK;" for transactional DDL), which keeps it from scoring lower, but checkpoints remain implicit, matching the anchor-3 profile.

3 / 5

Progressive Disclosure

Section structure is clear and consistent (Core Rules, Gotchas, Data Types, Constraints, Indexing, Partitioning, workload-specific sections), but the entire ~200-line reference is inlined in SKILL.md with no bundle files or pointers — detail-heavy sections like Extensions, JSONB Guidance, and the type-by-type catalogue are prime candidates for one-level-deep reference files. This lands between the anchor-2 inlined-content case and better organization, matching anchor 3.

3 / 5

Total

15

/

20

Passed

Description

88%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 explicitly states both what the skill covers and when to trigger it, with an enumerated trigger list and a dense keyword section. Minor gaps: a few natural synonym variants are absent and some triggers are broad enough to overlap with adjacent database skills.

DimensionReasoningScore

Specificity

The description lists multiple concrete, explicitly stated actions — "Design PostgreSQL tables, schemas, or data models", "Choose data types, constraints, or indexes", "Create user tables, order tables, reference tables, or JSONB schemas", "Design update-heavy, upsert-heavy, or OLTP-style tables" — comprehensively covering the table-design domain. Not a 4 because coverage spans design, type/constraint/index selection, table creation, workload patterns, and best practices with no meaningful gaps.

5 / 5

Completeness

Both "what" and "when" are explicit: "Use this skill for general PostgreSQL table design" backed by "Comprehensive reference covering data types, indexing strategies, constraints, JSONB patterns, partitioning", and an explicit "**Trigger when user asks to:**" list with concrete trigger phrases. Matches the anchor-5 pattern of clearly answering both with concrete triggers.

5 / 5

Trigger Term Quality

The keyword list ("PostgreSQL schema, table design, data types, PRIMARY KEY, FOREIGN KEY, indexes, B-tree, GIN, JSONB, constraints, normalization, identity columns, partitioning, row-level security") plus natural trigger phrases gives good coverage of terms users would say. Not a 5 because common variants like "Postgres" (without the SQL suffix), "DDL", or "CREATE TABLE" are missing.

4 / 5

Distinctiveness Conflict Risk

The niche (PostgreSQL table/schema design) is clear with PostgreSQL-specific triggers (JSONB, partitioning, identity columns). Not a 5 because broad triggers like "Choose data types, constraints, or indexes for PostgreSQL" and "Understand PostgreSQL best practices" could overlap with closely related skills such as query-optimization or general SQL design skills.

4 / 5

Total

18

/

20

Passed

Validation

93%

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

CriteriaDescriptionResult

metadata_version

'metadata.version' is missing

Warning

Total

15

/

16

Passed

Repository
timescale/pg-aiguide
Reviewed

Table of Contents

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.