Migrate Copilot customizations in VS Code
When VS Code shows a customization migration notice, it found a file, setting, or MCP server that Copilot does not read in its current location or format. Use the migration list to move or convert each affected customization.
This article explains why migration is needed, how to complete each migration that VS Code supports, and what to review manually.
This article covers migration to the Copilot harness. For Claude or Codex sessions, use the locations and formats in the provider documentation.
Open the migration list
A notice appears in chat when a workspace requires customization migrations. Select Review Migrations to open the list of migrations. To directy open the list of migrations:
- In the Chat view or Agents window, select Copilot as the Session Target.
- Run Chat: Open Customizations from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)).
- Select Migrations.
The migration tree groups the detected work by workspace and user scope.
Choose how to handle the migration:
- Migrate: select items in a group, review or change the destination when available, and select Migrate. VS Code performs the supported file move or conversion.
- Migrate with Agent: start a guided migration in chat for customizations that need semantic changes or repository work. This action uses Copilot credits. The agent creates a recovery bundle, preserves source files by default, and asks separately before it cleans up the source. For workspace migrations, it can prepare a pull request.
- Review: open an item under Needs manual review to understand why it cannot migrate automatically and edit its source configuration.
Use Ignore from a migration group's actions when you do not want to handle that group now. Select Show Ignored Migrations to restore ignored groups.
Before you migrate:
- Commit or back up workspace files that you might change.
- Review the source and destination shown for each item.
- Remember that the original and migrated copies do not synchronize.
- If you do not maintain the repository, use Migrate with Agent to prepare a pull request, or ask a repository maintainer to make the change.
You only need to migrate each item once. Keep the original until you verify the migrated customization, and then remove it when you no longer need it.
Why migration is needed
Earlier versions of VS Code stored some user customizations in profile user data and supported additional locations through chat.*FilesLocations settings. The Local agent reads those VS Code-specific sources.
The Copilot harness runs on Agent Host and uses the shared Copilot runtime that also powers GitHub Copilot CLI and the GitHub Copilot app. It reads customizations from Copilot folders and portable formats.
Moving customizations to those locations has these benefits:
- Agent Host can load them directly, including when it runs independently of the editor.
- Workspace customizations stay with the repository and can be shared through source control.
- VS Code and GitHub Copilot CLI read the same Copilot customization files. The GitHub Copilot app also uses repository and Copilot CLI skills and MCP server configuration.
- You can remove old location settings and avoid maintaining duplicate copies.
The destination depends on the migration type and scope. User-data migrations stay at user scope. Workspace migrations stay with the workspace. The migration tree shows the destination selected for each group.
For a complete list of customization types and supported locations, see the Copilot customization cheat sheet. Learn how these customizations appear in the GitHub Copilot app.
Migrate MCP servers
MCP server migration moves compatible configurations to files that the Copilot harness reads directly:
| Existing configuration | Destination |
|---|---|
Workspace .vscode/mcp.json |
.mcp.json at the corresponding workspace root |
VS Code profile mcp.json |
$COPILOT_HOME/mcp-config.json, or ~/.copilot/mcp-config.json when COPILOT_HOME is not set |
The automatic migration writes workspace servers to .mcp.json at the workspace root. Commit the file to source control when your team should share the configuration. For a remote or Dev Container session, paths and user configuration belong to the machine or container where Agent Host runs.
To migrate MCP servers:
- Expand the MCP Servers group for the workspace or your profile.
- Select the servers you want to migrate.
- Review the source, destination, and any properties that the destination format cannot preserve.
- Select Migrate for the group. You can also open one server and select Migrate from its detail page.
- Open the destination file and test the server with the Copilot harness.
VS Code writes and verifies each destination entry before removing the migrated entry from its source file. Unselected servers and servers that cannot be migrated stay in their current files.
A migration with changes can remove VS Code-specific metadata, including registry update information, version metadata, development-mode behavior, or per-server sandbox settings. The migration page lists the changes for each server.
Disabled state is not stored in .mcp.json or mcp-config.json. VS Code preserves workspace disablement in the current profile when possible, but user-level disablement can be lost. Other Copilot clients and other machines can treat the migrated server as enabled. Review the server's enabled state in each client before use.
Servers that cannot migrate automatically appear under Needs manual review. Select Review to open the server details and the source configuration. Resolve configuration errors, missing values, or duplicate server names, and then retry. You can also use Migrate with Agent for guided help. For MCP formats and supported locations, see Add and manage MCP servers.
Check MCP values before migration
Use the following table to decide whether a server can migrate automatically and what to review.
| Source configuration | Migration result | What to do |
|---|---|---|
Standard command, args, env, url, and headers values |
Migrates automatically and adds tools: ["*"] |
Inspect the server's tools. Replace * with the specific tools Copilot should invoke when you do not want every server tool available. |
${workspaceFolder}, ${workspaceRoot}, ${workspaceFolderBasename}, ${workspaceRootFolderName}, ${cwd}, or ${pathSeparator} |
Migrates after VS Code resolves the variable and writes its current value | Review the resulting value before you share the destination file or use it on another machine. |
gallery, version, dev, or sandboxEnabled |
Migrates with changes and removes these properties | Review the migration warning. Decide how to handle updates, development behavior, or sandboxing after migration. |
${input:...}, ${config:...}, ${command:...}, or other interactive VS Code variables |
Does not migrate automatically | Reconfigure the value for Copilot. Do not copy a resolved secret into the MCP file. |
${env:NAME} |
Does not migrate automatically | Use $NAME, ${NAME}, or ${NAME:-default}, and define the variable in the Agent Host environment. |
cwd |
Does not migrate automatically | Add cwd manually only when the server requires it, and verify the path on the Agent Host machine. |
envFile |
Does not migrate automatically | Export the required variables in the Agent Host environment and reference them from env. Do not copy secret values into the MCP file. |
| SSE transport | Does not migrate automatically | Use type: "sse" only when the server does not support Streamable HTTP. SSE is deprecated. |
A VS Code oauth object |
Does not migrate automatically | Remove the nested object to use OAuth discovery, or translate supported client settings to the flat Copilot OAuth fields. Authenticate when Copilot prompts you. |
Environment variables with null values |
Does not migrate automatically | Remove the entry or provide a supported value. |
| Additional VS Code-specific properties | Does not migrate automatically | Remove or replace the unsupported property before you retry. |
| A different server with the same name in the destination or another workspace root | Migration stops without changing the source | Rename or remove the conflicting server, and then retry. |
Input variables need special attention. The VS Code MCP format can prompt for values such as API keys through ${input:api-key}. The Copilot MCP format does not use this VS Code input flow, so these servers require manual configuration.
VS Code per-server sandbox settings and top-level sandbox rules do not transfer to Copilot configuration. Copilot uses session-level sandbox settings. Local stdio MCP servers run in the Copilot sandbox only when local sandboxing and MCP server sandboxing are enabled. Remote HTTP and SSE servers are not locally sandboxed. Review these settings before enabling a migrated server.
When a server requires manual work:
- Keep the original configuration until the Copilot server starts and provides the expected tools.
- Open the source configuration and identify each unsupported field or variable.
- Follow the Copilot CLI MCP server guidance for the destination configuration.
- Decide how to provide secrets, authentication, or environment-specific paths. Do not copy sensitive values into a committed file.
- Test the server with the Copilot harness before you remove the original entry.
Convert prompt files to skills
VS Code still supports *.prompt.md files in Local sessions, but Copilot sessions on Agent Host do not load them. Convert workspace and user prompt files to agent skills to keep the workflows available in Copilot sessions.
Converting a workspace prompt to a project skill changes how Copilot can use it. A prompt file runs only when someone invokes it. Copilot can select a committed skill automatically in VS Code, GitHub Copilot CLI, the GitHub Copilot app, Copilot cloud agent, and Copilot code review. Review the skill's description and instructions with the repository maintainer before you commit it. Convert a personal workflow to a user skill instead.
To convert prompt files:
- Expand Convert Prompt to Skills for the workspace or your profile.
- Select the prompt files to convert.
- Review the source and destination. Open a prompt if you want to inspect it.
- Select Migrate.
The generated skill includes disable-model-invocation: true, so it remains an explicitly invoked workflow. Conversion maps the prompt file's name, description, and argument guidance to the skill. It does not preserve prompt-specific agent, model, or tools selection. VS Code lists omitted properties after migration. If the prompt depends on a specific agent, model, or tool set, use Migrate with Agent to create a corresponding custom agent or adapt the workflow.
Test each skill before you remove the old prompt file.
Move user agents and instructions
The Copilot harness does not read custom agents and instructions stored in VS Code profile user data. User customization migration copies agents to ~/.copilot/agents and instructions to ~/.copilot/instructions without changing their names, types, or contents.
To move user customizations:
- Expand User Data under Your profile.
- Select the custom agents and instructions to move.
- Review the user destination shown for the group.
- Select Migrate.
The migrated files are not included in Settings Sync.
After migration, start a Copilot session and verify that the agents and instructions are available. See custom agent locations and instruction file locations for the supported destinations.
Move customizations from configured locations
The following settings add file locations for the Local agent, but the Copilot harness does not read them:
- chat.agentFilesLocations
- chat.modeFilesLocations
- chat.instructionsFilesLocations
- chat.agentSkillsLocations
Location migration moves detected custom agents, instructions, and skills to the Copilot folders for their scope:
| Customization | Workspace destination | User destination |
|---|---|---|
| Custom agents | .github/agents |
~/.copilot/agents |
| Instructions | .github/instructions |
~/.copilot/instructions |
| Skills | .github/skills or .agents/skills |
~/.copilot/skills or ~/.agents/skills |
To migrate custom locations:
- Expand Custom location settings for the workspace or your profile.
- Select the agents, instructions, and skills to move.
- Review or change the destination for the group.
- Select Migrate.
Prompt files from chat.promptFilesLocations are handled by prompt file migration, not location migration.
This migration applies only to the deprecated VS Code chat.*FilesLocations settings. GitHub Copilot CLI separately supports additional instruction directories through COPILOT_CUSTOM_INSTRUCTIONS_DIRS. VS Code does not migrate or clear that environment variable.
Customizations without automatic migration
The migration list does not automatically convert every customization type:
- Custom agents with Local-specific behavior: use Migrate with Agent when an agent depends on Local tool names, tool sets, hooks, or other behavior that needs semantic changes.
- Tool sets: Copilot does not support VS Code tool-set files. There is no automatic migration. Review the tools directly in the custom agent or chat tools picker. See Create and use tool sets.
- Hooks: there is no automatic hook migration. Configure hooks for Copilot using the GitHub Copilot hooks reference and Configure agent hooks.
- Plugins and marketplaces: manage these separately from the migration list. See Discover and install plugins.
- Extension-provided customizations: extensions can provide tools, MCP servers, custom agents, skills, and instructions. Keep the contributing extension installed. Extension tools are available only in editor chat while the extension runs. Learn more about Agent Host behavior on the extension host.
Verify the migration
After you complete a migration:
- Start a new Copilot session.
- Confirm that the migrated agents, instructions, skills, MCP servers, or plugins appear in the Agent Customizations editor.
- Run a representative task that uses the customization.
- Check that old and migrated copies are not both active.
- Commit workspace migrations to source control when your team should share them.
- Remove old files and settings after the migrated customization works.
For remote or Dev Container sessions, perform this check in the destination environment. User customization folders belong to the machine or container where the Agent Host runs.