スキルOfficialdevelopment

🚀output-migrate

プラグイン: outputai
ソース: GitHub で見る ↗

説明

プロジェクトをOutputフレームワークの旧バージョンから新バージョンへアップグレードします。次のような場合に使用: ユーザーがOutputの新バージョンへのアップグレード、マイグレーション、または移行を求めている場合。プロジェクト内の現在の `@outputai/*` バージョンを検出し、対応するマイグレーションガイドを `docs.output.ai` から取得して変更を適用し、プロジェクトの型チェックが引き続き通ることを確認します。

原文を表示

Upgrade a project between versions of the Output framework. Use when the user asks to upgrade, migrate, or move to a newer Output version. Detects the current @outputai/* version in the project, fetches the matching migration guide from docs.output.ai, applies the changes, and verifies the project still type-checks.

ユースケース

✓Outputの新バージョンへのアップグレードを求めているとき
✓プロジェクトの旧バージョンから新バージョンへのマイグレーション
✓Outputフレームワークの移行作業を行うとき

本文（日本語訳）

Output プロジェクトのマイグレーション

概要

このスキルは、Output フレームワークのあるバージョンから別のバージョンへプロジェクトをマイグレーションします。

マイグレーション手順はこのスキル自身のコンテキストには含まれていません。 https://docs.output.ai/migrations のドキュメントサイトが信頼できる情報源です — 該当ページを取得し、その手順に従ってください。

進捗管理には todo ツールを使用してください。

このスキルを使用するタイミング

ユーザーが @outputai/* パッケージを新しいバージョンにアップグレードしたい場合
ユーザーが「migrate」「upgrade」または「move to vX.Y.Z」といった言葉に言及している場合
破壊的変更を含むリリースが公開されており、ユーザーがまだ古いバージョンを使用している場合

URL の規約

マイグレーションガイドは、単一のインデックスページからリンクされた手作業で作成された MDX ページです:

インデックス: https://docs.output.ai/migrations
バージョン境界ごとのガイド: https://docs.output.ai/migrations/v{FROM_FULL}-to-v{TO_FULL}（例: v0.1.12-to-v0.2.0）

インデックスには、タイトルと短い説明を伴うすべての利用可能なガイドが掲載されています。ガイドが存在するのは破壊的変更が導入されたリリースのみです — ほとんどのリリースにはガイドはありません。

ユーザーが複数のバージョン境界をまたいで移行する場合は、該当する各ガイドを順番に取得し、順次適用してください。

手順

<process_flow>

ステップ 0: 引数の解析

ユーザーがこのスキルを呼び出す際に引数を渡した場合、以下の順序で位置引数として解析してください（すべて省略可能）:

from-version: プロジェクトが現在使用しているバージョン。空白の場合はステップ 2 で検出します。
to-version: 移行先のターゲットバージョン。空白の場合はステップ 1 で解決します。
additional-instructions: ユーザーからの自由形式のガイダンス（例:「http の変更はスキップしてください、そのパッケージは使っていません」）。

</step>

ステップ 1: 移行先（TO）バージョンの決定

ユーザーが to-version 引数を指定した場合はそれを使用します。

指定がない場合は、Bash で npm view @outputai/core version を実行し、その結果をターゲットバージョンとして使用します。

</step>

ステップ 2: 移行元（FROM）バージョンの検出

ユーザーが from-version 引数を指定した場合はそれを使用し、このステップの残りはスキップします。

指定がない場合は、プロジェクトルートの package.json を読み込み、以下の優先順位で最初に見つかったエントリから現在のフレームワークバージョンを解決してください:

dependencies["@outputai/core"]
devDependencies["@outputai/core"]
dependencies["@outputai/cli"]

先頭の ^ または ~ は取り除いてください。 @outputai/* パッケージが存在しない場合は処理を中止し、ユーザーに次のように伝えてください: 「このプロジェクトには @outputai/* パッケージへの依存関係がありません — マイグレーションの対象がありません。」

package.json から読み込んだバージョンが TO バージョンと一致する場合、ユーザーがマイグレーション実行前に package.json を新しいバージョンに手動で書き換えた可能性があります。諦めずに、以下の順序でバンプ前のバージョンを探してください:

git diff package.json pnpm-lock.yaml package-lock.json yarn.lock 2>/dev/null を実行し、差分の中から削除された（- で始まる行の）@outputai/* バージョンを探します。見つかった場合、それが FROM バージョンです。
git log -p -n 20 -- package.json を実行し、@outputai/* バージョンを変更した最新のコミットを探します。そのコミットの親側にある古い値が FROM バージョンです。
どちらでも特定できない場合は、ユーザーに次のように伝えてください: 「FROM バージョンを検出できません — package.json と git 履歴の両方が vX.Y.Z を示しています。--from <version> を付けて再実行し、バージョンを明示的に指定してください。」

この復元処理を経ても FROM と TO が同じバージョンになる場合は処理を中止し、ユーザーに次のように伝えてください: 「すでに vX.Y.Z を使用しています — マイグレーションの必要はありません。」

</step>

ステップ 3: マイグレーションガイドの取得

https://docs.output.ai/migrations を WebFetch します。このインデックスページには、バージョン境界ごとにキーが付けられた手作業で作成されたすべてのマイグレーションガイドへのリンクが含まれています。

インデックスから、ユーザーの FROM バージョンと TO バージョンの間に該当する v{FROM}-to-v{TO} 形式のすべてのガイドを特定してください。例:

ユーザーの FROM が 0.1.12、TO が 0.2.0 の場合 → インデックスに v0.1.12-to-v0.2.0 ガイドが掲載されていればそれを取得します。
ユーザーの FROM が 0.1.12、TO が 0.3.0 の場合 → まず v0.1.12-to-v0.2.0 を取得し、次に（掲載されていれば）v0.2.0-to-v0.3.0 を取得します。
同一マイナーバージョン境界内に複数のパッチレベルのガイドがある場合は、すべてを時系列順に適用してください。

該当する各ガイドは https://docs.output.ai/migrations/v{FROM_FULL}-to-v{TO_FULL} を取得することで入手してください。

インデックスに FROM → TO の範囲をカバーするガイドが存在しない場合は処理を中止し、ユーザーに次のように伝えてください: 「vFROM → vTO に対するマイグレーションガイドが見つかりませんでした。この範囲のリリースは追加的な変更のみです。依存関係のバージョンを上げるだけで対応できます。」

また、https://docs.output.ai/changelog も WebFetch し、該当範囲でリリースされた内容をクロスリファレンスとして確認してください — マイグレーションガイドがカバーしていない箇所の補完に活用します。

</step>

ステップ 4: 変更計画の作成

取得したガイドをもとに、具体的な変更内容を TodoWrite リストとして作成します（変更 1 件につき todo 1 件）。この時点ではまだ編集を開始しないでください。

各 todo には以下の情報を記載してください:

影響を受けるファイル（ガイドに記載されている非推奨 API の呼び出し箇所を Grep で検索して特定）
変更内容（可能な限り diff 形式で）
参照したガイドのセクション

ユーザーが additional-instructions を渡した場合はそれを反映してください: スキップを求められた todo は除外し、追加を求められた todo は追加します。

計画を表示し、進める前にユーザーに確認を求めてください。拒否された場合は処理を中止します。

</step>

ステップ 5: 変更の適用

各 todo を順番に処理します。それぞれの todo について:

開始前に in_progress としてマークする。
Edit/MultiEdit で変更を適用する。
完了したら completed としてマークする。

複数の完了をまとめて記録しないでください — 1 件ごとに TodoWrite を更新してください。

</step>

ステップ 6: 依存関係のバンプ

package.json 内のすべての @outputai/* パッケージと（存在する場合）output-api エントリを TO バージョンに更新します。このフレームワークは固定バージョングループを採用しているため、すべてのパッケージを同時に更新します。

その後、pnpm install を実行してください（ロックファイルから検出して npm install または yarn install に切り替えてください）。

</step>

ステップ 7: 検証

設定されている場合は、プロジェクトの型チェッカーを実行します（package.json のスクリプトに typecheck、tsc、または build がないか確認してください）。

型チェックが失敗した場合は、各エラーとそれに対応するマイグレーションガイドのセクションを合わせて提示してください。サイレントな自動修正は試みないでください — 何が壊れたかを報告してください。

型チェックスクリプトが存在しない場合はその旨を記載し、テストスイートを実行するようユーザーに推奨してください。

</step>

ステップ 8: サマリー

以下の内容を報告してください:

FROM → TO バージョン
使用したマイグレーションガイドの URL
変更されたファイルの一覧
型チェックの結果
ユーザーが手動で確認すべき事項（ガイドが判断を要すると明記していた箇所）

追加のコマンドや次のステップは提案しないでください — マイグレーション後のメッセージングは CLI が処理します。

</step>

</process_flow>

原文（English）を表示

Migrate an Output Project

Overview

This skill migrates a project from one version of the Output framework to another.

You do not carry migration instructions in your own context. The docs site at https://docs.output.ai/migrations is the source of truth — fetch the right page and follow it.

Use the todo tool to track your progress.

When to Use This Skill

The user wants to upgrade @outputai/* packages to a newer version
The user mentions "migrate", "upgrade", or "move to vX.Y.Z"
A breaking-change release shipped and the user is still on an older version

URL contract

Migration guides are hand-authored MDX pages linked from a single index:

Index: https://docs.output.ai/migrations
Per-boundary guide: https://docs.output.ai/migrations/v{FROM_FULL}-to-v{TO_FULL} (e.g. v0.1.12-to-v0.2.0)

The index lists every available guide with a title and a short description. A release only has a guide if it introduced breaking changes — most releases will not have one.

If the user is jumping multiple boundaries, fetch each applicable guide in order and apply them sequentially.

Instructions

<process_flow>

Step 0: Arguments Analysis

If the user passed arguments when invoking this skill, parse them as positional values in this order (all optional):

from-version: The version the project is currently on. If blank, detect it in Step 2.
to-version: The target version. If blank, resolve it in Step 1.
additional-instructions: Free-form guidance from the user (e.g. "skip the http changes, we don't use that package").

</step>

Step 1: Determine the target (TO) version

If the user provided a to-version argument, use it.

Otherwise, run npm view @outputai/core version via Bash and use that as the target.

</step>

Step 2: Detect the current (FROM) version

If the user provided a from-version argument, use it and skip the rest of this step.

Otherwise, read package.json at the project root and resolve the current framework version from the first entry that exists, in this order:

dependencies["@outputai/core"]
devDependencies["@outputai/core"]
dependencies["@outputai/cli"]

Strip any leading ^ or ~. If no @outputai/* package is present, stop and tell the user: "This project doesn't depend on any @outputai/* packages — nothing to migrate."

If the version read from package.json equals the TO version, the user may have already edited package.json to the new version without running the migration yet. Don't give up — find the pre-bump version by looking in this order:

Run git diff package.json pnpm-lock.yaml package-lock.json yarn.lock 2>/dev/null and scan the diff for an @outputai/* version that was removed (lines starting with -). If you find one, that's the FROM version.
Run git log -p -n 20 -- package.json and find the most recent commit that changed an @outputai/* version. The old value on that commit's parent side is the FROM version.
If neither locates a prior version, tell the user: "Cannot detect the FROM version — both package.json and git history show vX.Y.Z. Re-run with --from <version> to specify it explicitly."

If FROM and TO still resolve to the same version after this recovery, stop and tell the user: "Already on vX.Y.Z — nothing to migrate."

</step>

Step 3: Fetch migration guides

WebFetch https://docs.output.ai/migrations. This is the index page — it links to every hand-authored migration guide with a title keyed on the version boundary.

From the index, identify every guide whose v{FROM}-to-v{TO} range falls between the user's FROM and TO versions. Examples:

User FROM 0.1.12, TO 0.2.0 → if a v0.1.12-to-v0.2.0 guide is listed, fetch it.
User FROM 0.1.12, TO 0.3.0 → fetch v0.1.12-to-v0.2.0 first, then (if listed) v0.2.0-to-v0.3.0.
Multiple patch-level guides between the same minor boundaries should all be applied in chronological order.

Fetch each applicable guide by hitting https://docs.output.ai/migrations/v{FROM_FULL}-to-v{TO_FULL}.

If the index lists no guides covering the FROM → TO range, stop and tell the user: "No migration guides found for vFROM → vTO. The releases in this range were additive; just bump your dependencies."

Also WebFetch https://docs.output.ai/changelog to cross-reference what shipped in the range — use it to fill in gaps the migration guides may not cover.

</step>

Step 4: Plan the changes

From the fetched guide(s), produce a TodoWrite list of concrete changes, one todo per change. Do not start editing yet.

For each todo, capture:

Which file(s) are affected (use Grep to find call sites for deprecated APIs the guide mentions).
What the change is (diff-shaped if possible).
Which guide section it came from.

If the user passed additional-instructions, honor them: skip todos they asked to skip, add todos they asked to add.

Print the plan and ask the user to confirm before proceeding. If they reject, stop.

</step>

Step 5: Apply the changes

Work through each todo. For every todo:

Mark it in_progress before starting.
Apply the change with Edit/MultiEdit.
Mark it completed when done.

Do not batch completions — update TodoWrite after each one.

</step>

Step 6: Bump dependencies

Update every @outputai/* package and (if present) output-api entry in package.json to the TO version. The framework uses a fixed version group, so all packages move together.

Then run pnpm install (or npm install / yarn install — detect from the lockfile).

</step>

Step 7: Verify

Run the project's type checker if one is configured (check package.json scripts for typecheck, tsc, or build).

If type checking fails, surface each error with the migration guide section that maps to it. Do not attempt silent fixes — report what broke.

If the project has no type check script, note that and recommend the user run their test suite.

</step>

Step 8: Summary

Report:

FROM → TO version
Which migration guide URL(s) were used
List of files modified
Type-check result
Anything the user should verify manually (things the guide flagged as needing judgment)

Do not suggest additional commands or next steps — the CLI handles post-migration messaging.

</step>

</process_flow>

原文・著作権は Anthropic および各プラグイン作者に帰属します。日本語訳は Claude API による自動翻訳です。