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.
git clone --depth 1 https://github.com/omnigent-ai/omnigent /tmp/migration-guide && cp -r /tmp/migration-guide/examples/scribe/skills/migration-guide ~/.claude/skills/migration-guideSKILL.md
# 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.Spin up a live local Omnigent server + runner and exercise the native Antigravity (agy) TUI harness (antigravity-native) end-to-end — launch the real `agy` CLI via `omnigent antigravity`, drive turns through the web UI, smoke-test, and bug-bash. Load when developing, testing, or debugging the antigravity-native harness (omnigent/inner/antigravity_native_executor.py, omnigent/antigravity_native.py, antigravity_native_bridge.py, antigravity_native_rpc.py, antigravity_native_reader.py, antigravity_native_launch.py) or its agy launch / RPC mirror / tmux delivery / OAuth / MCP-relay behavior. NOT the in-process `antigravity` Gemini SDK harness.
Spin up a live local Omnigent server and exercise the Antigravity (Gemini) SDK harness end-to-end — build antigravity agents, run real turns, smoke-test, and bug-bash. Load when developing, testing, or debugging the antigravity harness (omnigent/inner/antigravity_executor.py, antigravity_harness.py, omnigent/onboarding/antigravity_auth.py) or its auth / model / tool-bridge behavior.
Document a module or public API surface (functions, classes, CLI commands, endpoints) from the code itself. Use when the user asks for API reference, to document a module, or to write usage docs for a public interface.
Patterns and templates for generating valid Omnigent agent directories. Load when ready to create files.
Verify the Omnigent CLI's setup/onboarding flow, terminal UI/UX, and critical user journeys in a completely isolated, reproducible loop. Drives the real `omnigent` binary through a PTY (pexpect) inside a throwaway OMNIGENT_CONFIG_HOME / OMNIGENT_DATA_DIR sandbox that never touches the user's real ~/.omnigent, captures ANSI-stripped frames for UX inspection, and proves a change is verifiable via a before→fix→after baseline diff. Load when developing or reviewing a CLI setup/onboarding/REPL/picker change (omnigent/cli.py, omnigent/onboarding/*, omnigent/repl/*, scripts/install_oss.sh), reproducing a cold-start/first-run UX bug, or confirming a fix actually lands. Several agents can run it concurrently on separate worktrees.
Test counter — codex skills e2e. The unique suffix b8d4e7 appears in the skill name so a string match in the agent's output proves codex loaded this skill.
Test greeter — codex skills e2e. The unique suffix a3f9c2 appears in the skill name so a string match in the agent's output proves codex loaded this skill.
Spin up a live local Omnigent server and exercise the GitHub Copilot SDK harness end-to-end — build copilot agents, run real turns, smoke-test, and bug-bash. Load when developing, testing, or debugging the copilot harness (omnigent/inner/copilot_executor.py, copilot_harness.py, omnigent/onboarding/copilot_auth.py) or its auth / model / tool-bridge behavior.