Agent Skills › omnigent-ai/omnigent › migration-guide

migration-guide

GitHub

生成 Breaking Change 的迁移升级指南，通过对比旧版与新版 API、配置或模块的变化，提供机械可验证的步骤和 Before/After 示例，帮助用户平滑过渡。

examples/scribe/skills/migration-guide/SKILL.md omnigent-ai/omnigent

Trigger Scenarios

用户询问如何从旧版本升级到新版本需要处理 API 重命名、参数移除或默认值变更等破坏性更新

Install

npx skills add omnigent-ai/omnigent --skill migration-guide -g -y

More Options

Non-standard path

npx skills add https://github.com/omnigent-ai/omnigent/tree/main/examples/scribe/skills/migration-guide -g -y

Use without installing

npx skills use omnigent-ai/omnigent@migration-guide

指定 Agent (Claude Code)

npx skills add omnigent-ai/omnigent --skill migration-guide -a claude-code -g -y

安装 repo 全部 skill

npx skills add omnigent-ai/omnigent --all -g -y

预览 repo 内 skill

npx skills add omnigent-ai/omnigent --list

SKILL.md

Frontmatter

{
    "name": "migration-guide",
    "description": "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."
}

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.