Content
68%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.
A code-dense, highly actionable reference that respects token budget and stays free of concept padding. Its weakest point is workflow clarity: destructive database operations get principles ("always backup, always support rollback") but no explicit validated sequence, and one programmatic snippet mishandles downgrade offsets.
Suggestions
Add an explicit ordered workflow with validation checkpoints for migrations: backup → verify the backup exists/is non-empty → migrate → confirm the new revision with `alembic current` / `get_migration_status()` → roll back via `downgrade` if verification fails.
Trim the Quick Reference table to rows not already shown verbatim above (e.g., keep history/current/pg_dump rows, drop the duplicated autogenerate/upgrade/downgrade rows), and de-duplicate the timestamp/backup logic between `backup_postgres` and `backup_sqlite`.
Fix the programmatic `migrate()` so negative relative offsets route to `command.downgrade` instead of `command.upgrade`, and replace the "Edit migrations/env.py..." comment with the two or three concrete lines actually needed in env.py.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The body is dominated by executable code with almost no concept explanation — the Overview is two sentences and comments are sparse — matching the "efficient with minor trimming" anchor. Not 5 because the Quick Reference table repeats commands already shown verbatim (e.g., `alembic revision --autogenerate`, `alembic upgrade head`, `alembic downgrade -1`), and the backup functions duplicate the timestamp logic and imports, so not every token earns its place; not 3 because there is no unnecessary explanation of concepts Claude already knows. | 4 / 5 |
Actionability | Guidance is mostly executable: copy-paste-ready Alembic commands, working functions for status checks, version-tracked raw SQL, transactional psycopg2 migration, and backups. Not 5 because of minor gaps: the programmatic `migrate()` routes negative offsets like "-1" to `command.upgrade`, which is invalid in Alembic (relative downgrade belongs to `command.downgrade`), and the "Edit migrations/env.py to set your DATABASE_URL and metadata" setup step is hand-waved rather than shown. | 4 / 5 |
Workflow Clarity | Sections imply a rough order (setup → generate → apply → check; ensure table → apply → track) and some checks exist (`get_migration_status`, transactional rollback in `pg_migrate`), but there is no explicit sequenced workflow with validation checkpoints for these destructive/batch database operations. The rubric caps workflow clarity at 3 when destructive or batch operations lack validation steps — no checkpoint verifies the backup succeeded or confirms the post-migration revision, and the Overview's "Always backup before migrating" principle is never wired into an ordered procedure. Not 2 because the per-tool procedures are individually coherent and error-handling/rollback code is present. | 3 / 5 |
Progressive Disclosure | No bundle files exist and the ~155-line body is organized into well-labeled sections (Alembic, raw SQL, PostgreSQL, backup, quick reference) with a navigable summary table — good structure with content appropriately inline for this size. Not 5 because the skill exceeds the under-50-line simple-skill case and the programmatic Alembic/raw-SQL code blocks could plausibly live in reference files; not 3 because organization is clear, not in need of restructuring. | 4 / 5 |
Total | 15 / 20 Passed |