CtrlK
BlogDocsLog inGet started
Tessl Logo

alonso-skills/postgres-writing-guidelines

Use when writing or reviewing PostgreSQL/PL-pgSQL, designing table schemas, writing functions and procedures, building migrations, defining domains, or architecting a Postgres application database. Also use when writing RAISE EXCEPTION patterns, BEFORE/AFTER triggers for cross-table constraints, base/subtype hierarchies, composite key designs, row-level security policies, or idempotent DDL scripts. If you are touching Postgres for an application database, use this skill. PostgreSQL-specific — examples will not run on other engines.

71

Quality

89%

Does it follow best practices?

Impact

No eval scenarios have been run

SecuritybySnyk

Passed

No known issues

Overview
Quality
Evals
Security
Files

Quality

Content

72%

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

This is a strong, comprehensive PostgreSQL skill that provides highly actionable guidance with concrete SQL examples and excellent progressive disclosure through well-organized reference links. Its main weakness is length — the Common Mistakes table partially duplicates earlier sections, and some topics could be more tightly compressed. The skill would also benefit from explicit multi-step workflow sequences with validation checkpoints for operations like schema migrations or base/subtype table creation.

Suggestions

Add an explicit step-by-step migration workflow with validation checkpoints (e.g., 1. Write DDL → 2. Run in dev → 3. Verify with \d table → 4. Check constraints with pg_catalog query → 5. Apply to staging).

Trim the Common Mistakes table by removing entries that directly repeat guidance already covered in dedicated sections above (e.g., snake_case, domains as NOT NULL, timestamptz) — or consolidate into a quick-reference checklist format.

DimensionReasoningScore

Conciseness

The skill is generally efficient and avoids explaining basic concepts Claude already knows, but it's quite long (~500+ lines) with some sections that could be tightened. The Common Mistakes table at the end is extensive and some entries repeat guidance already covered in earlier sections (e.g., snake_case, domains, timestamptz). However, most content earns its place as domain-specific conventions Claude wouldn't inherently know.

2 / 3

Actionability

The skill provides concrete, executable SQL examples throughout — CREATE DOMAIN definitions, RLS policies, trigger functions, queue claim CTEs, migration DDL with IF NOT EXISTS, and reference table seeding. Code is copy-paste ready PostgreSQL, not pseudocode, and covers real production patterns with specific syntax.

3 / 3

Workflow Clarity

The skill covers many individual patterns clearly but lacks explicit multi-step workflow sequences with validation checkpoints. For example, the migration section shows idempotent DDL but doesn't provide a step-by-step migration workflow with validation. The base/subtype section references triggers but doesn't show the full creation sequence with verification. For a skill involving destructive operations (migrations, schema changes), explicit validation steps would strengthen this.

2 / 3

Progressive Disclosure

The skill excels at progressive disclosure — the main body provides concise overviews with key examples for each topic, then consistently links to dedicated reference files (e.g., 'read [Naming Conventions](references/naming-conventions.md)'). References are one level deep, clearly signaled with descriptive link text, and the main document serves as a navigable overview. However, no bundle files were provided to verify the references actually exist.

3 / 3

Total

10

/

12

Passed

Description

100%

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

This is a strong skill description that excels across all dimensions. It provides comprehensive, specific capabilities with rich trigger terms that a PostgreSQL developer would naturally use, clearly states both what it does and when to use it, and explicitly distinguishes itself from other database skills. The only minor note is that it's slightly verbose, but the detail serves the purpose of disambiguation well.

DimensionReasoningScore

Specificity

Lists multiple specific concrete actions: writing/reviewing PostgreSQL/PL-pgSQL, designing table schemas, writing functions and procedures, building migrations, defining domains, RAISE EXCEPTION patterns, BEFORE/AFTER triggers, base/subtype hierarchies, composite key designs, row-level security policies, idempotent DDL scripts.

3 / 3

Completeness

Clearly answers both 'what' (PostgreSQL schema design, functions, triggers, migrations, etc.) and 'when' with explicit trigger guidance ('Use when writing or reviewing PostgreSQL...', 'Also use when...', 'If you are touching Postgres for an application database, use this skill').

3 / 3

Trigger Term Quality

Excellent coverage of natural terms users would say: PostgreSQL, PL-pgSQL, Postgres, table schemas, functions, procedures, migrations, triggers, row-level security, DDL scripts, domains, composite keys. These are terms a developer would naturally use when seeking help with PostgreSQL.

3 / 3

Distinctiveness Conflict Risk

Clearly scoped to PostgreSQL/Postgres specifically, with the explicit note 'PostgreSQL-specific — examples will not run on other engines.' This creates a distinct niche that would not conflict with general SQL or other database engine skills.

3 / 3

Total

12

/

12

Passed

Validation

100%

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

Validation11 / 11 Passed

Validation for skill structure

No warnings or errors.

Reviewed

Table of Contents