Content
70%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 highly actionable, tool-specific migration guidance with exemplary validation gates and checklists on its risky workflows. Its weaknesses are redundancy (duplicate activation sections, timeline restating phases), one non-executable batch code block, and broken references to example files that are absent from the bundle.
Suggestions
Merge the duplicate "When to Activate" and "When to Use This Skill" bullet lists into a single section, and cut the Timeline Example that restates the phase list.
Create the referenced examples/postgres-add-column.sql and examples/postgres-column-rename.sql files, or remove the links — they currently point to nonexistent paths.
Fix the batched backfill example to use a CALL-able PROCEDURE (or an app-side loop) since COMMIT inside a DO block fails with invalid transaction termination.
Consider moving the per-ORM sections (Prisma, Drizzle, Django, golang-migrate) into one-level-deep reference files so SKILL.md stays an overview.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The content is mostly dense and code-first, but "When to Activate" and "When to Use This Skill" are near-duplicate five-bullet lists, and the "Timeline Example" restates the phase description immediately above it. This matches anchor 3 (mostly efficient, some content that could be tightened) better than 4, where trimming would be minor. | 3 / 5 |
Actionability | Nearly all guidance is copy-paste-ready: ALTER TABLE variants with lock caveats, concurrent index DDL, expand-contract SQL, complete Django migration code, and per-tool CLI workflows. The batched DO $$ ... COMMIT ... END $$ block is not executable as written (COMMIT cannot appear inside a DO block — it requires a PROCEDURE), and rename Step 2 is prose-only, so minor gaps keep it at anchor 4 rather than 5. | 4 / 5 |
Workflow Clarity | The expand-contract rename is a 7-step sequence with an explicit validation gate ("Require zero mismatches before switching reads"), retry feedback ("retry failed batch transactions"), a pre-flight safety checklist, and documented rollback plans — the database/batch feedback-loop requirement is fully met, matching anchor 5. It is not 4 because the risky workflows (backfill, cutover, contract) all carry explicit checkpoints. | 5 / 5 |
Progressive Disclosure | Section headers are clear, but the ~420-line body inlines per-ORM reference material that could live in separate files, and the two example links (examples/postgres-add-column.sql, examples/postgres-column-rename.sql) point to files that do not exist in the bundle, so navigation fails at exactly those references. This fits anchor 3 (structure present but organization/reference gaps) rather than 4, where gaps would be minor. | 3 / 5 |
Total | 15 / 20 Passed |