Migrate customizations to the Copilot harness in VS Code
AI agents: See llms.txt for documentation discovery and navigation. Documentation articles are also available as Markdown by appending .md to the article URL. Join VS Code at Microsoft Ignite or catch the sessions online. A year of VS Code, wrapped. Explore the highlights. Migrate customizations to the Copilot harness in VS Code View as Markdown Ask in VS Code Ask in VS Code Insiders Move your existing Local customizations to the Copilot harness without losing the workflows you rely on.
Use the migration list for supported file moves and conversions, then verify the result with a representative task before retiring the original setup. Start with the path for your customization below. You don't need to complete every migration in this article. For answers about keeping Local available, MCP secrets, custom discovery paths, and agent tool names, see the migration FAQ . The Local harness The Local harness is deprecated and will be removed in February 2027.
Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation . is deprecated and will be removed by February 2027 . Complete your customization migration before then. For the broader workflow transition, including session continuity, organization rollout, and policy verification, follow Move from Local to the Copilot harness . Note This article covers migration to the Copilot harness.
For the Claude or Codex harness, use the locations and formats in the provider documentation. Claude and Codex harnesses are disabled when Copilot enterprise-managed settings apply , unless your administrator explicitly permits them. Contact the IT team that deployed the settings to discuss access. Choose a migration path Existing customization Destination or replacement How to migrate What to recheck Workspace or profile MCP servers Portable Copilot MCP configuration Migrate compatible server entries .
Review unsupported properties manually. Authentication, available tools, enabled state, and sandbox settings Workspace or user prompt files Project or user skills Convert prompt files . Use Migrate with Agent when the workflow also needs an agent or tool configuration. Explicit invocation and any omitted agent , model , or tools properties Agents and instructions in profile user data Copilot user folders Move user customizations .
Discovery and behavior in a new Copilot session Files in configured search locations Native workspace or user folders Move files from configured locations . Destination scope and duplicate active copies Hooks in files, settings, agents, or plugins Supported Copilot hook sources and scripts Migrate hooks manually . No automatic hook conversion is available. Event timing, script inputs and outputs, approvals, and failure paths User-defined tool sets Workflow-specific tool configuration Replace tool-set references .
Required capabilities and tool restrictions Chat participants A publisher-provided replacement or a direct agent request Replace participant workflows . Service access, attached context, and expected results Plugins or extension-provided customizations A compatible installation Manage these separately . Publisher setup, harness compatibility, and required extensions Use the publisher guidance only if you maintain a participant implementation.
Installing a replacement doesn't require you to build a plugin. Open the migration list Before changing a customization: Commit or back up workspace files, scripts, and user settings that you might change. Choose a small task that works with the original customization. Record its expected result, required tools, and approvals so you can compare them after migration. Review the source and destination for each item. Original and migrated copies don't synchronize.
If you don't maintain the repository, use Migrate with Agent to prepare a pull request, or ask a repository maintainer to make the change. A notice appears in chat when a workspace requires customization migrations. Select Review Migrations to open the list. To open it directly: 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.
Keep your backup until you verify the migration . Automatic MCP migration removes successfully migrated source entries, while Migrate with Agent preserves source files by default. Where an original remains, retire it only after verification and avoid leaving both copies active. Why migration is needed The Copilot harness reads customizations from Copilot folders and portable formats. Move custom agents, instructions, and skills from editor-specific storage and configured custom locations to native harness folders so they can be discovered across Copilot clients.
VS Code can forward files from configured locations for compatibility with existing editor workflows, but other clients do not inherit those settings. Note For Local harness sessions The Local harness is deprecated and will be removed in February 2027. Move your workflows to the Copilot harness before then. Learn more about Local harness deprecation . : The agent reads VS Code profile customizations and the additional locations configured through those settings.
Moving a customization for the Copilot harness doesn't change which sources the Local harness reads. Moving customizations to those locations has these benefits: The Copilot harness can load them directly without relying on an editor to provide them. 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: Migration is different from editor forwarding , which can make eligible existing definitions available without moving their configuration. Neither path preserves every editor-specific capability. Check MCP support and limitations if your workflow depends on prompts, resources, sampling, or interactive UI.
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 sessio
The rest of this page is on the live site.