postgresql-table-design

Use this skill when designing or reviewing a PostgreSQL-specific schema. Covers best-practices, data types, indexing, constraints, performance patterns, and advanced features

Quality

62%

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./plugins/database-design/skills/postgresql/SKILL.md

Quality

Discovery

67%

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

The description has a clear 'Use when' clause and identifies the domain well, but relies on category names rather than specific concrete actions. It would benefit from more natural trigger term variations (e.g., 'Postgres', 'database design') and more specific capability descriptions instead of broad topic areas like 'advanced features'.

Suggestions

Replace broad category names with specific concrete actions, e.g., 'Designs normalized table structures, selects appropriate PostgreSQL data types, creates indexes for query optimization, defines foreign keys and check constraints'.

Add common trigger term variations such as 'Postgres', 'database design', 'table structure', 'DDL', 'CREATE TABLE', and 'database schema' to improve matching.

Replace the vague 'advanced features' with specific examples like 'partitioning, JSONB columns, custom types, or materialized views' to reduce conflict risk with other skills.

Dimension	Reasoning	Score
Specificity	Names the domain (PostgreSQL schema design/review) and lists several topic areas (data types, indexing, constraints, performance patterns, advanced features), but these are categories rather than concrete actions like 'create indexes', 'normalize tables', or 'define foreign key constraints'.	2 / 3
Completeness	Explicitly answers both 'what' (covers best-practices, data types, indexing, constraints, performance patterns, advanced features) and 'when' ('Use this skill when designing or reviewing a PostgreSQL-specific schema'), providing a clear trigger clause.	3 / 3
Trigger Term Quality	Includes relevant keywords like 'PostgreSQL', 'schema', 'indexing', 'constraints', 'data types', and 'performance', which users might naturally mention. However, it misses common variations like 'Postgres', 'database design', 'table structure', 'migrations', 'DDL', or '.sql'.	2 / 3
Distinctiveness Conflict Risk	The PostgreSQL-specific qualifier helps distinguish it from general database skills, but terms like 'performance patterns', 'constraints', and 'indexing' could overlap with general SQL or database optimization skills. The 'advanced features' phrase is particularly vague and could conflict with other PostgreSQL-related skills.	2 / 3
	Total	9 / 12 Passed

Implementation

57%

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

This is a comprehensive and highly actionable PostgreSQL schema design reference with excellent concrete examples and specific guidance. Its main weaknesses are its monolithic structure—everything is packed into a single file with no progressive disclosure—and some verbosity in sections like data types and extensions that could be split into reference files. The workflow clarity is adequate but lacks explicit validation checkpoints for destructive operations like schema migrations.

Suggestions

Split detailed subsections (Data Types, JSONB Guidance, Extensions, Partitioning) into separate reference files and link from a concise overview in the main SKILL.md

Add explicit validation/verification steps to the 'Safe Schema Evolution' section, e.g., 'Run EXPLAIN on critical queries after schema change to verify index usage'

Trim the data types section to focus on PostgreSQL-specific gotchas and non-obvious choices, removing entries Claude would already know (e.g., basic BOOLEAN usage)

Dimension	Reasoning	Score
Conciseness	The skill is dense with useful information and avoids explaining basic concepts, but it's quite long (~300+ lines) with some sections that could be tightened or moved to reference files (e.g., the exhaustive data types list, TOAST storage details, and full extensions catalog). Some items like explaining what MVCC dead tuples are border on unnecessary for Claude.	2 / 3
Actionability	Provides concrete, executable SQL examples throughout (CREATE TABLE, CREATE INDEX, ALTER TABLE), specific operator syntax, exact function names, and copy-paste ready code blocks. The examples section at the end demonstrates complete, runnable table definitions with indexes and constraints.	3 / 3
Workflow Clarity	The 'Safe Schema Evolution' section provides sequenced steps but lacks explicit validation checkpoints or feedback loops. The 'Insert-Heavy Workloads' section lists steps (drop index, load, recreate) but without validation. For destructive operations like schema changes, there are no explicit verify-before-proceeding checkpoints beyond mentioning transactional DDL.	2 / 3
Progressive Disclosure	The entire skill is a monolithic document with no references to external files for detailed subsections. The data types section, JSONB guidance, extensions list, and special considerations could each be separate reference files linked from a concise overview. Everything is inline, making it a wall of dense text.	1 / 3
	Total	8 / 12 Passed

Validation

100%

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 — 11 / 11 Passed

Validation for skill structure

No warnings or errors.

Repository: wshobson/agents
Commit: 27a7ed9

Reviewed: 5 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.