Guide · Agent skill

How to use the PostgreSQL Table Design agent skill

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

The PostgreSQL Table Design skill is a set of PostgreSQL-specific schema rules that an AI agent follows when you ask it to design or review database tables. It is aimed at developers creating a new schema, engineers auditing an existing one, and teams planning a change to a live database. After this guide you will know how to install the skill, how to phrase requests so it triggers, what it checks, and where its limits are.

PostgreSQL Table Designwshobson/agents · MIT Download the skill

Quick start

1Download the ZIP. Download the skill ZIP from this page and unzip it. It contains SKILL.md and references/details.md.
2Choose an install location. Unzip into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder to limit it to that project.
3Or upload it in the apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
4Describe your PostgreSQL task. Ask for schema design or review in plain language and name PostgreSQL, for example a review of your CREATE TABLE statements.
5Provide DDL, queries and version. Share your table definitions, main queries and PostgreSQL version so the advice matches your workload.
6Verify before shipping. Test recommended indexes, partitioning and types against your own data before applying them to production.

What the skill makes the agent do

When the skill is active, the agent applies PostgreSQL schema best practices to your table design or review. It recommends suitable data types, such as TIMESTAMPTZ for times and NUMERIC for money, and flags missing primary keys, unindexed foreign key columns and missing NOT NULL constraints. It also suggests indexing, partitioning and JSONB approaches where they fit.

Column types: for example TIMESTAMPTZ instead of timestamp, and TEXT instead of char(n) or varchar(n).
Keys and constraints: primary keys, foreign keys with ON DELETE/UPDATE behaviour, UNIQUE, CHECK and EXCLUDE.
Indexes: B-tree, composite, covering, partial, expression, GIN, GiST and BRIN, with guidance on when each applies.
Partitioning and semi-structured data: when to partition a large table and when to use JSONB.

Install the skill from the ZIP

Download the ZIP for this skill from this page and unzip it. The skill is a folder containing SKILL.md and a references folder with details.md. Place the folder in one of the locations below so the agent can load it.

For a personal install across projects, unzip it into ~/.claude/skills/. To limit it to a single project, unzip it into that project's .claude/skills/ folder instead.

You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.

Personal: ~/.claude/skills/postgresql-table-design/
Project only: .claude/skills/postgresql-table-design/ inside your repository

Trigger the skill with natural requests

You do not need a special command. The skill is described as being used when designing or reviewing a PostgreSQL-specific schema, so ask for that work in plain language and name PostgreSQL explicitly. Naming the database matters because the rules are PostgreSQL-specific.

Design: "Design a PostgreSQL schema for a multi-tenant invoicing app with users, invoices and line items."
Review: "Review this PostgreSQL CREATE TABLE statements for missing foreign key indexes and risky types."
Partitioning: "Should this 200M-row events table in PostgreSQL be partitioned, and on which column?"
Live change: "Plan a column addition on our live PostgreSQL orders table with minimal downtime."

Examples of what the agent produces

For a new table, the skill's guidance leads to a definition like the one below: an identity primary key, a NOT NULL unique email, a TIMESTAMPTZ creation time with a default, and an index on a lookup expression. The orders example adds a foreign key, a CHECK on allowed status values and an index on the referencing column.

For a JSONB attributes column, the skill suggests a GIN index on the JSONB column and a generated column for a frequently read scalar value.

CREATE TABLE users (
  user_id BIGINT GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
  email TEXT NOT NULL UNIQUE,
  name TEXT NOT NULL,
  created_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
CREATE UNIQUE INDEX ON users (LOWER(email));
CREATE INDEX ON users (created_at);

What it needs and what it does not do

The skill itself is guidance text. It does not run scripts and does not use the network. A PostgreSQL database or SQL tooling is only needed if you ask the agent to run statements against one.

The guidance is general rules of thumb. Performance claims, such as the 100M-row threshold for partitioning, should be checked against your own workload before you act on them.

Runs scripts: no
Uses network: no
Requires a database only if you ask the agent to execute statements
Non-PostgreSQL databases such as MySQL or SQL Server are not covered; the rules may mislead there

Tips for better results

Give the agent your PostgreSQL version. Several rules depend on it: NULLS NOT DISTINCT needs PG15+, uuidv7() needs PG18+, and foreign keys on partitioned tables have version-specific support. Paste your real DDL and the main queries, because the indexing advice depends on access paths you actually run.

Include the PostgreSQL version and the top queries with their filters and sorts.
Ask for the reasoning behind each recommendation so you can test it.
For deep material such as the full type catalogue or worked DDL, ask the agent to consult references/details.md.
Test suggested indexes and partitioning with EXPLAIN on realistic data before shipping.

What people use it for

Designing a new PostgreSQL schema for an application before its first production release.
Reviewing an existing schema for missing foreign-key indexes, missing NOT NULL constraints and risky types such as timestamp without time zone.
Deciding whether a large time-series table should be range-partitioned on its timestamp column.
Planning a schema change on a live database with attention to avoiding downtime.
Choosing between JSONB attributes and normal columns for semi-structured data.

Frequently asked questions

How do I install the PostgreSQL table design skill?

Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder for one project. You can also upload it in the Claude apps under Settings → Capabilities → Skills.

Do I need a PostgreSQL database to use this skill?

No. The skill is guidance text, so it works without a database. A PostgreSQL database or SQL tooling is only needed if you ask the agent to run statements.

Is the PostgreSQL table design skill free?

The skill is published under the MIT licence. This page does not list pricing, so check the source repository for licence terms in full.

Does this skill run scripts or use the internet?

According to the listing, it runs no scripts and uses no network. It consists of SKILL.md and a reference file, details.md.

Can I use this skill for MySQL or SQL Server?

No. The rules are PostgreSQL-specific and may mislead on other databases such as MySQL or SQL Server. Use a skill written for your database instead.

Why isn't the agent following the skill?

Check that the folder is named postgresql-table-design and sits directly in ~/.claude/skills/ or .claude/skills/, and that SKILL.md is inside it. Then name PostgreSQL in your request so the skill's description matches.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Use this skill if you design or review PostgreSQL schemas and want a consistent checklist covering types, keys, indexes and partitioning. Pick something else if you use a non-PostgreSQL database, or if you need performance guarantees, since the guidance is general rules of thumb that you must verify against your own workload.

Download the skill