/migrate-customizations

name: migrate-customizations
description: Guide a safe, reversible migration of VS Code local agent customizations when launched from the Agent Customizations Migrations page with VS Code-generated migration context.
argument-hint: Launch from Agent Customizations > Migrations > Migrate with Agent
user-invocable: true
disable-model-invocation: true

Migrate Agent Customizations

Guide the user through migrating the inventory included in the invoking prompt. The source locations and valid target folders in that prompt were evaluated for the selected harness. Treat them as authoritative: do not substitute hardcoded destination paths or migrate to a folder that is not listed.

Required Migration Context

Before doing anything else, verify that the invoking prompt includes all of the following VS Code-generated values:

• Selected harness
• Migration telemetry flow
• Recovery bundle folder and filesystem path
• Customizations that need migration
• Valid target folders reported by the selected harness

If any value is missing, do not inspect, copy, move, convert, or delete customizations. Explain that this workflow must be started from **Agent Customizations > Migrations** by selecting **Migrate with Agent**, then stop. Do not ask the user to manually reconstruct or paste the missing context.

Read [migration techniques](./references/migration-techniques.md) before proposing changes.

Safety Contract

1. Never modify a customization before creating a recovery bundle. 2. Use the recovery bundle folder supplied in the invoking prompt. VS Code created and is watching this folder; do not move it or substitute another location. 3. In the recovery bundle, create:

• `migration-log.md`, containing the selected harness, scope, timestamps, source and destination paths, commands or tools used, validation results, and every user decision.
• `backups/`, containing a byte-for-byte copy of every file before its first modification or deletion.
• `restore.md`, containing exact steps for restoring the backups and reverting newly created files.
• `migration-results.json`, containing only the privacy-safe aggregate schema described in Finish. VS Code watches this file for the final migration outcome.

4. Append to the log after every attempted operation, including failures and rollbacks. 5. Approval to migrate a group authorizes destination writes only; it does not authorize deleting source files, removing source MCP entries, or clearing location settings. Preserve sources by default. After the destination is validated, ask separately for explicit approval for each kind of cleanup. If runtime validation is not possible, explain what was and was not verified, keep the source, and ask whether to defer cleanup. 6. Stop on an unexpected source change, destination conflict, invalid configuration, failed backup, or failed validation. Explain the problem instead of guessing. 7. Never include customization names, paths, contents, MCP configuration, or other user data in telemetry. 8. Classify each inventory item exactly once using its supplied category and scope. Do not offer the same item again in another group; if groups overlap, explain the overlap and use the item's inventory category to decide where it is handled.

Workflow

1. Choose Scope

Ask whether to migrate:

• user customizations,
• workspace customizations, or
• both.

Do not act on an unselected scope.

If workspace customizations are selected, ask whether the user wants a pull request. If they do, keep workspace changes focused, include the validation evidence and migration rationale in the pull request, and do not include a recovery bundle stored outside the repository.

2. Review the Plan

Classify the supplied inventory by its reported category and scope, then handle applicable items in this order:

1. prompt files that should become skills; 2. VS Code profile user-data agents, instructions, and skills; 3. MCP servers; 4. workspace or user customizations at locations defined by settings `chat.agentSkillsLocations`, `chat.instructionsFilesLocations`, and `chat.agentFilesLocations`.

The groups are mutually exclusive for an inventory item. In particular, a file reported under `configuredLocations` belongs in group 4, not group 2, even if its type is agent, instruction, or skill. If a previously skipped item would otherwise reappear in a later group, do not ask about it again unless the user requests reconsideration.

Before each group:

• explain why the migration is useful;
• list the source and harness-reported destination locations;
• describe changes that cannot be preserved;
• state explicitly that approval covers destination writes only and that source cleanup will require a separate approval;
• ask for confirmation to proceed with that group.

Work one group at a time. Do not request approval for all writes at once.

3. Migrate Prompt Files to Skills

Explain the compatibility reason for converting each prompt to a skill. Convert each selected prompt into a skill directory with a `SKILL.md`, preserving supported name, description, argument guidance, invocation semantics, and body content. Add `disable-model-invocation: true` when needed to preserve an explicit-invocation-only prompt. Record unsupported frontmatter in the log for review; do not silently drop behavior.

Validate that each skill has valid frontmatter, a meaningful description, and a folder name that matches the skill name. Distinguish structural validation from runtime validation: test discovery and representative invocation in the selected destination harness when possible. A file inspection or a test against a different harness is not proof that the destination harness loads the skill. If runtime validation requires a new session or is otherwise unavailable, say so, leave the source in place, and defer cleanup unless the user explicitly chooses otherwise after hearing the limitation.

4. Migrate User Data

Explain that Agent Host doesn