Content
63%Weight 40%Scale 1-5Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The body delivers strong, concrete migration guidance — GOOD/BAD SQL patterns, safety checklists, and a clear expand-contract strategy — but it is a monolithic file that inlines five ORM-specific references and ~80 lines of schema boilerplate Claude already knows. Splitting per-ORM content into references/ and fixing the invalid COMMIT-in-DO-block example would lift it substantially.
Suggestions
Split the Prisma, Drizzle, Kysely, Django, and golang-migrate sections into one-level-deep references/ files (e.g. "Prisma: See [prisma.md](prisma.md)"), keeping the shared principles, checklist, and PostgreSQL patterns in SKILL.md.
Fix the large-backfill example: COMMIT is invalid inside a DO block — move batching into a procedure or use explicit per-batch transactions in application code.
Drop the Prisma/Drizzle schema-definition examples and the Kysely migrator boilerplate, which re-teach what Claude already knows and add no migration-specific value.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Mostly efficient — the GOOD/BAD SQL comparisons, checklist, and anti-pattern table earn their tokens — but roughly 80 lines re-teach what Claude already knows: full Prisma and Drizzle schema definitions ("model User { ... }", "pgTable(\"users\"...)") and the Kysely migrator boilerplate, which are not migration guidance. Not 4 because that padding is more than a minor instance (it spans three sections); not 2 because the majority of the body is high-value, non-obvious operational knowledge with no prose padding. | 3 / 5 |
Actionability | Concrete, copy-paste-ready SQL and CLI commands throughout ("CREATE INDEX CONCURRENTLY idx_users_email ON users (email)", "npx prisma migrate dev --create-only --name add_email_index", the expand-contract step sequences). Not 5 because the batched-update example is not actually executable as written: "COMMIT" inside a DO block's LOOP is invalid in PL/pgSQL (transaction control is only allowed in procedures called via CALL), so the flagship large-backfill pattern fails if run verbatim. | 4 / 5 |
Workflow Clarity | Multi-step processes are clearly sequenced with validation artifacts: the pre-migration checklist ("Probado contra una copia de datos de producción", "Plan de rollback documentado"), the numbered rename/drop sequences, the phased expand-contract strategy with a day-by-day timeline, and recovery guidance ("Forzar versión (corregir estado sucio)", "Verificar consistencia de datos" in Fase 2). Not 5 because no workflow includes an explicit fail-then-act feedback loop (e.g., what to check and do when a migration fails or a backfill stalls mid-batch), and the batch example reports progress via RAISE NOTICE but never verifies results; not 3 because checkpoints are genuinely present, not merely implicit, so the missing-feedback-loop cap at 3 does not apply. | 4 / 5 |
Progressive Disclosure | Good internal structure with clear section headers, but it is a ~430-line monolith: the five per-ORM sections (Prisma, Drizzle, Kysely, Django, golang-migrate) are exactly the content that belongs in one-level-deep references/ files, since a Django user currently loads Drizzle, Kysely, and Go content on every activation. Scored 3 rather than 2 because there are no buried or nested references and the body is well-organized with clear navigation, fitting the "content that should be separate is inline" anchor; not 4 because no reference split or navigation to external material exists at all. | 3 / 5 |
Total | 14 / 20 Passed |