Content
80%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body is exceptionally lean and actionable with executable SQL throughout, but it is a monolithic single-file reference lacking progressive disclosure into bundle files and explicit validation feedback loops for destructive DDL operations.
Suggestions
Split the large reference sections (Data Types, Extensions, JSONB Guidance) into separate reference files and link to them one level deep from SKILL.md to improve progressive disclosure.
Add explicit validation checkpoints for destructive/batch DDL — e.g. wrap migrations in transactions and verify with a query before committing, or run a dry-run check after schema changes.
Add a brief 'safe migration workflow' (test in transaction -> validate -> commit) to convert the scattered evolution notes into a sequenced, checkpointed process.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Dense, declarative bullet lists with zero introductory padding — e.g. 'Prefer TIMESTAMPTZ for event time; NUMERIC for money' — assume Claude's competence and earn every token, matching the 'lean and efficient' anchor. | 3 / 3 |
Actionability | Provides executable SQL throughout — copy-paste-ready examples (Users/Orders/JSONB tables), concrete commands ('CREATE INDEX CONCURRENTLY', 'ALTER TABLE ... SET STORAGE'), and exact syntax, matching the 'fully executable' anchor. | 3 / 3 |
Workflow Clarity | Sequenced guidance exists in places (e.g. 'BEGIN; ALTER TABLE...; ROLLBACK', 'drop index, load data, recreate indexes') but there are no explicit validation checkpoints or validate-fix-retry feedback loops for destructive/batch DDL, which the scoring notes say should cap workflow_clarity at 2. | 2 / 3 |
Progressive Disclosure | Content is well-organized into clear sections, but the SKILL.md is a ~200-line monolithic body with no bundle files or one-level-deep references to split out the large reference material (data types, extensions, JSONB guidance), matching the 'some structure but content that should be separate is inline' anchor. | 2 / 3 |
Total | 10 / 12 Passed |