Guide · Agent skill
How to use the Migration Review agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The migration-review skill is a set of instructions and a small script that an AI coding agent can load when a code change adds or edits database migration files under a migrations/ folder. It tells the agent to review only those files, check them against a written checklist, and produce a structured report before the change is merged. This guide explains what the skill does, how to install it, how to trigger it with plain requests, what it needs, and where its limits are.
Migration Reviewrohitg00/ai-engineering-from-scratch · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it so the skill folder contains SKILL.md, references/review-checklist.md and scripts/check_scope.py.
- 2Place it where the agent can load it. Put the folder in ~/.claude/skills/ for personal use or in your project's .claude/skills/ folder, or upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Confirm Python 3 is available. Make sure python3 runs on your machine, because the bundled scope checker needs it.
- 4Make your change under migrations/. Add or edit the migration files in a migrations/ folder. The checker rejects paths outside that folder.
- 5Ask for a pre-merge review. Request a migration review in plain language and name the files or the branch.
- 6Read the report. Check the Scope, Evidence, Risks, Rollback and Blockers sections, then read the Decision. A blocked decision means required evidence is missing.
- 7Make the call yourself. Use the report as evidence for your own review. The skill does not approve production changes.
What is an agent skill and what does migration-review make the agent do?
An agent skill is a folder of instructions that an AI agent such as Claude Code can load and follow for a specific kind of task. The migration-review skill covers one task: reviewing database schema changes before they merge.
When a change adds or modifies paths under migrations/, the skill directs the agent to check only the named migration files and the code needed to verify their compatibility. For each file it looks at how the migration behaves going forward, how it could be rolled back, whether it could lock tables or touch large amounts of data, and what evidence is missing.
The output is a report with six headings: Scope, Evidence, Risks, Rollback, Blockers, and Decision. If required evidence is missing, the decision is marked blocked. The skill does not apply any migration.
- Forward behavior: the schema and data transition and compatibility with the currently deployed application version.
- Rollback: whether reversal is safe, lossy, or impossible, and the restore or compensating path if it is not possible.
- Lock and volume risk: estimated locks, transaction duration and affected row volume.
- Evidence: the exact validation command and result, with each risk linked to a file and statement.
How do you install the migration-review skill?
Download the ZIP of the skill from this page and unzip it. You can install it in one of two ways.
For personal use, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder. Either way, the skill folder should contain SKILL.md, references/review-checklist.md and scripts/check_scope.py.
If you use the Claude apps instead, open Settings, go to Capabilities, and upload the skill under Skills.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
How do you trigger the skill with a natural request?
You do not need a special command. Ask the agent for a pre-merge review of migration changes in plain language, and name the migration files or the change. The skill's description tells the agent to use it when a change adds or modifies paths under migrations/ and the review is before merge.
The skill passes the files you name to its scope checker. The checker only accepts paths under migrations/, so a request that names other files will be stopped at the scope step.
- "Review the migration files in this branch before I merge."
- "Check migrations/0042_add_orders_index.sql for rollback and locking risks."
- "Run the migration review on the new files under migrations/ and give me the Decision."
What does a review run look like?
The skill's instructions tell the agent to run the bundled checker on the files you name, stop if any path is outside migrations/, read the review checklist, inspect each accepted file and its schema assumptions, and then report. The checker is invoked with python3 from the skill's own folder.
The skill's allowed-tools entry pre-approves only that one checker command for the invocation turn. It does not remove other tools or replace your project's permission rules, so the agent may still ask before running other commands.
python3 ${CLAUDE_SKILL_DIR}/scripts/check_scope.py $ARGUMENTSWhat do you need before you run it?
You need Python 3 available so the bundled scope checker can run. You also need Claude Code or a compatible agent that has the Read, Grep, Glob, and Bash tools. The skill runs scripts and does not use the network.
Your project must have migration files under a migrations/ folder, using SQL or Python as the team's migration format. The skill is built for teams that want reviews to follow the same checklist each time.
- Python 3 on the machine
- Claude Code or a compatible agent with Read, Grep, Glob and Bash
- Migration files under a migrations/ folder
What are the safety notes?
The skill runs a script, scripts/check_scope.py, so read it before you install if your policy requires it. The script is only pre-approved for the one invocation pattern shown above. The skill makes no network calls.
The skill gathers evidence but does not judge production safety. A human must read the report and make the approval decision. The skill also does not verify the database against a live system, so any claim about real data volume or live locks must come from you or from your own checks.
- Runs scripts: yes, the bundled scope checker.
- Uses network: no.
- It does not apply migrations.
- It does not connect to or verify a live database.
What tips help the review go well?
Give the agent the exact migration files and the validation command you ran, if you have one. The checklist asks for the exact command and result, so a review with that evidence can reach a decision, while one without it will usually be marked blocked.
Keep destructive cleanup in a separate migration from the compatibility change. The checklist asks for this, and it makes rollback clearer. If you expect production volume to matter, tell the agent so it can note that evidence is missing.
- Name the files under migrations/ explicitly.
- Supply the validation command and its result.
- Give production volume estimates when you have them.
- Keep destructive cleanup separate from the compatibility migration.
What people use it for
- Checking a new SQL migration that adds a column before merge and noting whether the currently deployed app still works with it.
- Reviewing a Python migration that backfills rows, with the agent flagging transaction duration and affected row volume as missing evidence.
- Confirming that a destructive cleanup has been split out of the compatibility migration and that the rollback path is stated.
- Applying one consistent checklist across several engineers' migration pull requests on the same team.
Frequently asked questions
How do I install the migration-review skill?
Download the ZIP from this page and unzip it into ~/.claude/skills/ for personal use, or into a project's .claude/skills/ folder. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
What do I need to run migration-review?
You need Python 3 for the bundled scope checker, plus Claude Code or a compatible agent with the Read, Grep, Glob, and Bash tools. Your project needs migration files under a migrations/ folder.
Is migration-review free and what is its licence?
The item is listed under the MIT licence. The source does not state any price, so check the repository for the terms that apply to you.
Does the skill apply or run my migrations?
No. The skill states that it does not authorize applying a migration. It gathers evidence and produces a report, and it does not verify the database against a live system.
Why does the skill reject my files?
The scope checker only accepts paths under migrations/. If you name any other path, the skill is told to stop at the scope step.
Can I use migration-review as my only production approval?
No. The skill gathers evidence but a human must judge the result. A blocked decision means required evidence, such as production volume or compatibility evidence, is missing.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use migration-review if your team keeps SQL or Python migrations in a migrations/ folder and wants every pre-merge review to follow the same checklist and produce the same report. Pick something else if your project has no migrations under that folder, or if you need a tool that checks a live database or makes production approval decisions for you.
Download the skill