Guide · Agent skill
How to use the Safe Migration Planner agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Safe Migration Planner is an agent skill: a packaged set of instructions that changes how an AI coding agent handles risky changes to databases, APIs, protocols, configuration, or dependencies. This guide explains what the skill makes the agent do, how to install it, how to trigger it with plain requests, and where its limits are. After reading, you should be able to install the skill, ask the agent for a staged migration with a rollback path, and know what to review before anything reaches production.
Safe Migration PlannerJuliusBrussee/caveman · Apache-2.0 Download the skill Quick start
- 1Download the ZIP. Get the skill ZIP from this page and unzip it on your machine.
- 2Place the folder. Move the unzipped folder into ~/.claude/skills/ for all projects, or into .claude/skills/ inside one project.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill there instead.
- 4Describe the change. Ask for the migration in plain language, naming the system, the old and new versions, and what must keep working.
- 5Review the map and rollback path. Check the readers, writers, compatibility window, ownership, and forward and rollback paths before any edits.
- 6Approve stages one at a time. Verify each stage, then explicitly approve contraction only when you are ready for destructive steps.
What the migration skill makes the agent do
When installed, the agent approaches changes to schemas, data formats, APIs, protocols, configuration, or dependencies more carefully than it would by default. Before editing, it maps the current readers and writers, the data shape, the compatibility window, and who owns each part.
The skill asks the agent to work in stages: expand, migrate, verify, then contract where that applies. It defines both a forward path and a rollback path, keeps old and new versions safe to run side by side, and makes retries idempotent and partial failures visible.
- Preserves existing data and treats destructive steps as explicit, separately authorized actions.
- Verifies both the old and the new paths at the transition stages that need it.
- Stops after the stage you requested passes, instead of running later contraction steps on its own.
Install the migration skill
Download the skill ZIP from this page and unzip it. To make the skill available to Claude Code across your projects, place the unzipped folder in ~/.claude/skills/. To scope it to a single project, place it in that project's .claude/skills/ folder instead.
If you use the Claude apps, you can upload the skill under Settings → Capabilities → Skills rather than unzipping it into a folder yourself.
- Personal install: ~/.claude/skills/
- Project install: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
Trigger the skill with natural requests
You do not need a special command. The skill's description covers schema, data, API, protocol, configuration, and dependency migrations that require rollback and preservation proof, so ask for those things in plain language and name the system and the constraint that matters.
Good requests say what is changing, who uses the old version, and what must keep working. The more the agent knows about the compatibility window, the better the map it builds before editing.
- "Plan a staged migration to add a non-null column to the orders table without breaking the current writer."
- "Move our user API from v1 to v2 while mobile clients on v1 are still active. Include a rollback path."
- "Change the config format for the worker service. Show me how old and new workers run side by side."
- "Upgrade the auth library across three services. Map which services depend on it and add a verification step before cleanup."
Review the plan before anything changes
Ask the agent to show its map of readers, writers, compatibility window, and ownership before it edits files. Check that the forward path and rollback path are both written down and that every destructive step is labelled as needing separate approval.
Because the skill pauses before contraction, you decide when that step runs. Treat each stage as a checkpoint: confirm the verify stage passed and the old and new paths still work before asking for the next one.
- Confirm the compatibility window and owners are correct.
- Check the rollback path is concrete, not just a sentence saying 'revert'.
- Approve contraction explicitly, and only after verification.
Safety notes: scripts and network access
The skill's listing states that it runs no scripts and uses no network access. It requires nothing else to be installed. Its files are agents/openai.yaml and SKILL.md.
The skill guides the agent's approach; it does not replace human review. Any production change still needs a person to look at it, including the verification evidence the agent produces.
- Runs scripts: no
- Uses network: no
- Requires: nothing listed
- Files: agents/openai.yaml, SKILL.md
- Licence: Apache-2.0
When not to use this skill
The staged process adds overhead that is not worth it for quick one-off scripts or throwaway projects. It is also not a way to approve destructive operations: it is designed to pause before contraction, but a human must still review and authorize those steps.
- Skip it for throwaway scripts and small disposable projects.
- Do not rely on it to make destructive changes safe without your own review.
What people use it for
- Adding a column or changing a column type on a live database while the current application keeps writing to it.
- Rolling out a v2 API where mobile or third-party clients on v1 must keep working during the overlap.
- Changing a configuration format for a service that runs multiple instances during a rolling deploy.
- Upgrading a shared dependency across several services, with a verification step before removing the old code path.
Frequently asked questions
How do I install the migration agent skill?
Download the skill ZIP from this page and unzip it. Place the folder in ~/.claude/skills/ for personal use across projects, or in .claude/skills/ inside a specific project. In the Claude apps, you can instead upload it under Settings → Capabilities → Skills.
Does the migration skill require anything else to be installed?
The listing states that it requires nothing else. It does not run scripts and does not use the network. Its files are agents/openai.yaml and SKILL.md.
Is the Safe Migration Planner free to use?
The source material for this page does not state pricing or licence terms beyond the licence identifier, which is Apache-2.0. Check the repository's licence file for the full terms before using it commercially.
How do I trigger the migration skill?
Ask for a migration in plain language that mentions a schema, data, API, protocol, configuration, or dependency change. Name the system and the constraint that must keep working, such as an old client version that must stay active.
Will the agent delete my data during a migration?
The skill tells the agent to preserve existing data and to treat destructive steps as explicit and separately authorized. It stops after the stage you requested and does not run contraction steps on its own, but you should still review any production change.
When should I not use this skill?
Avoid it for quick one-off scripts or throwaway projects, where the staged process adds unnecessary overhead. It is also not a substitute for human review of destructive operations.
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
The migration skill suits engineers who need a staged, reversible plan for database, API, protocol, configuration, or dependency changes and want evidence that old and new paths both work. Skip it for throwaway projects or quick scripts, and do not treat it as approval for destructive production changes, which still need human review.
Download the skill