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.
84
89%
Does it follow best practices?
Impact
100%
1.72xAverage score across 2 eval scenarios
Passed
No known issues
Quality
Discovery
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 listing numerous PostgreSQL-specific tasks, includes abundant natural trigger terms that developers would use, explicitly states when to use the skill with multiple 'Use when' clauses, and clearly distinguishes itself as PostgreSQL-specific. The only minor note is that it's somewhat long, but the density of useful information justifies the length.
| Dimension | Reasoning | Score |
|---|---|---|
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, RLS policies, etc.) and 'when' with explicit trigger guidance ('Use when writing or reviewing PostgreSQL/PL-pgSQL...', '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, table schemas, functions, procedures, migrations, triggers, row-level security, DDL scripts, Postgres, domains, composite keys. These are terms developers naturally use when working with PostgreSQL. | 3 / 3 |
Distinctiveness Conflict Risk | Very clearly scoped to PostgreSQL specifically, with the explicit note 'PostgreSQL-specific — examples will not run on other engines.' This creates a clear niche distinct from general SQL skills or other database engine skills. | 3 / 3 |
Total | 12 / 12 Passed |
Implementation
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 executable SQL examples throughout. Its progressive disclosure structure is exemplary, with concise overviews pointing to detailed reference files. The main weaknesses are occasional verbosity in explanatory prose and the lack of explicit multi-step workflows with validation checkpoints for operations like migrations and schema changes.
Suggestions
Add an explicit step-by-step migration workflow with validation checkpoints (e.g., 'write DDL → dry-run with \i in a transaction → verify with \d → COMMIT or ROLLBACK'), especially since migrations are destructive operations.
Trim explanatory prose that restates concepts Claude already knows — for example, the 'Consistency' and 'Semantic inference' bullets under DOMAINs could be condensed to a single line each, and the 'Two Access Rules' preamble could be shortened.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is comprehensive and mostly efficient, but some sections explain concepts Claude already knows (e.g., what snake_case is, basic transaction semantics, what DOMAINs are). The 'Common Mistakes' table is extensive and valuable but could be tightened. Several sections include light explanatory prose that could be trimmed without losing actionability. | 2 / 3 |
Actionability | The skill provides executable SQL throughout — CREATE DOMAIN examples, RLS policy definitions, trigger+function patterns, queue claim CTEs, idempotent migration DDL, and reference table seeding. Code is copy-paste ready and PostgreSQL-specific. The Common Mistakes table gives concrete fix patterns for each anti-pattern. | 3 / 3 |
Workflow Clarity | While individual patterns are clearly explained, the skill lacks explicit multi-step workflow sequences with validation checkpoints. For example, the migration section doesn't show a step-by-step 'write migration → validate → apply → verify' workflow. The base/subtype section references triggers but doesn't sequence the full creation order with verification steps. For a skill covering destructive operations like migrations, explicit validation checkpoints would strengthen this. | 2 / 3 |
Progressive Disclosure | The skill excels at progressive disclosure — each major topic gets a concise overview with executable examples in the main file, then clearly signals a one-level-deep reference file (e.g., 'read [Naming Conventions](references/naming-conventions.md)'). The structure is consistent and navigable, with 20+ well-signaled reference links. However, no bundle files were provided to verify the references actually exist, so scoring is based on the structural pattern alone. | 3 / 3 |
Total | 10 / 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.
Validation — 11 / 11 Passed
Validation for skill structure
No warnings or errors.
Reviewed
Table of Contents