# Migration Guide

> Turn a breaking change (an API rename, removed flag, changed default, or moved module) into concrete upgrade steps with before/after examples. Use when the user asks how to migrate, upgrade, or adapt to a breaking change.

- Skill: `omnigent-ai/migration-guide` (Agent Skill)
- Install (CLI): `npx skillmds@latest add omnigent-ai/migration-guide`
- Raw SKILL.md: https://api.skillmd.com/api/skills/omnigent-ai/migration-guide/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: omnigent-ai (https://skillmd.com/u/omnigent-ai)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/omnigent-ai/migration-guide

---


# migration-guide — write upgrade steps for a breaking change

Produce a guide that lets a user on the old version land on the new one with the
least friction.

## Pin down what actually broke

Identify the precise breaking change before writing a word. Get it from the diff
and history, not from the description alone:
- `git diff <old>..<new>` on the affected surface, and `gh pr view <n>` for the
  PR that introduced it.
- Dispatch the researcher (`purpose: explore`) to confirm the exact old and new
  shapes: the old name/signature/default, the new one, and whether a
  compatibility shim or deprecation window exists.

Never document a rename or signature change from memory — the exact symbols are
what users will copy.

## Structure

    # Migrating to <version>

    ## What changed
    <one paragraph: the change and why, in user terms>

    ## Upgrade steps
    1. <ordered, mechanical steps>

    ## Before / after
    ```
    # before
    ...
    # after
    ...
    ```

    ## If you can't upgrade yet
    <deprecation window, shim, or flag to opt out — if one exists>

## Write the steps

- Make each step mechanical and verifiable ("rename `--foo` to `--bar`", not
  "update your flags"). A user should be able to follow it without rereading the
  whole guide.
- Show a minimal, real before/after for each distinct change. Keep examples
  copy-pasteable.
- State explicitly when there is no automated path and a manual edit is
  required.

## Verify

Route the finished guide through the `reviewer` (`purpose: review`). Migration
guides are acted on directly, so a wrong flag name or step is high-cost — the
cross-vendor fact-check is worth it here.