Track customization migration readiness for Agent Host

## Summary

As Agent Host becomes the default harness, some customizations that work in VS Code's local harness do not carry over unchanged. The incompatibility can be in the **location**, **file format**, or **contents**—for example, a custom agent can remain in `.github/agents` but reference tool names that are unavailable in the new harness.

Every existing customization entry point needs one of three outcomes:

1. work natively in GitHub Copilot CLI / the Copilot SDK;
2. be moved or converted to a supported entry point; or
3. show a clear explanation and next step when automated migration is not safe.

This issue is the public inventory of those entry points and their migration readiness.

## Established direction

- Customization discovery is owned by the harness/SDK. Agent Host will not inherit VS Code-specific discovery settings such as `chat.agentFilesLocations`.
- Existing files must not silently stop working. Detect legacy entry points and offer an optional, one-time migration.
- Prefer portable, harness-owned locations and formats over new VS Code-specific compatibility layers.
- The Agent Customizations editor is the home for reviewing and completing migrations. Contextual entry points elsewhere should link into it.
- Preserve originals until migration succeeds or the user explicitly approves their removal.
- Long-term synchronization across machines and hosts remains a separate question.

## Target outcome

- Personal and workspace customizations continue working through native discovery or explicit migration.
- Unsupported locations, formats, and references are detected before they cause silent failures.
- Users can understand and review what will move, convert, register, or be rewritten.
- Migrated customizations are validated in the intended local or remote host.
- Telemetry measures remaining legacy use and migration outcomes without collecting customization contents.

## Migration-readiness inventory

The table uses one row per distinct compatibility problem. A shared location does not imply a shared format, so custom-agent fields, hook definitions, and referenced scripts are tracked separately.

### Status

- ✅ Supported or migration shipped
- 🟡 Partially implemented, experimental, or not rolled out
- ⬜ Migration needed
- ❓ Compatibility decision or investigation needed

| Type | Scope | VS Code entry point / format | Copilot CLI / SDK expectation | Telemetry | Migration |
|---|---|---|---|---|---|
| Prompt files | Workspace | `.github/prompts/*.prompt.md` | Product direction is to deprecate `.prompt.md`; convert existing prompt files to skills rather than carrying the format into Agent Host | Detect files and record offer, accept, success, failure, and dismissal | ✅ Prompt-to-skill migration enabled by default; see [#332262](https://github.com/microsoft/vscode/pull/332262) and [test plan #330793](https://github.com/microsoft/vscode/issues/330793) |
| Prompt files | User | VS Code profile User Data `*.prompt.md` | Convert to personal skills | Same as workspace, split by scope | ✅ Prompt-to-skill migration enabled by default through [#332262](https://github.com/microsoft/vscode/pull/332262) |
| Prompt files | Workspace or user | Additional paths and globs in `chat.promptFilesLocations` | Copilot CLI does not consume the VS Code setting; discover every configured source before conversion | Record configured paths and files found per path | ⬜ Extend migration discovery beyond default folders |
| Legacy chat modes | Workspace or user | `.github/chatmodes/*.chatmode.md` and paths in deprecated `chat.modeFilesLocations` | Convert `.chatmode.md` to `.agent.md` in a supported agent folder | Record legacy files and conversion outcome | ⬜ Migration flow needed |
| Custom agents | Workspace | `.github/agents/*.agent.md` with shared frontmatter | Same folder and file type | Validate discovery and activation by host | ✅ Baseline |
| Custom agents | Workspace or user | Additional paths in `chat.agentFilesLocations` | Copilot CLI does not consume the VS Code setting; move to `.github/agents` or `~/.copilot/agents` | Record configured paths and files found | ⬜ Migration flow needed |
| Custom agents | User | VS Code profile User Data agents | Move to `~/.copilot/agents/*.agent.md` | Record files found and move/copy outcomes | 🟡 User Data migration exists but is not fully rolled out; see [planning #8196](https://github.com/microsoft/vscode-internalbacklog/issues/8196) (internal), [missing user agents #322137](https://github.com/microsoft/vscode/issues/322137), and [migration failure #331335](https://github.com/microsoft/vscode/issues/331335) |
| Custom agents | Workspace or user | Legacy or VS Code-specific names in `tools` | Rewrite to supported Copilot tool names and namespaces without widening permissions | Record unresolved names and rewrites | ⬜ Tracked by [#328121](https://github.com/microsoft/vscode/issues/328121); prior naming alignment in [#272734](https://github.com/microsoft/vscode/issues/272734) |
| Custom agents | Workspace or user | References to VS Code user tool sets in `tools` | Expand to supported concrete tool names, or define a shared tool-set format | Record unresolved tool-set references | ❓ Decision needed |
| Custom agents | Workspace or user | VS Code-specific frontmatter, handoffs, or deprecated properties | Validate each field against the shared custom-agent schema and preserve intent where possible | Record incompatible properties | ❓ Inventory and compatibility mapping needed |
| Custom agents | Workspace or user | Hooks embedded in `.agent.md` frontmatter | Confirm support; otherwise extract into a supported hook file without changing agent scope | Record agent-scoped hooks and conversion result | ❓ Compatibility decision needed |
| Instructions | Workspace | `.github/copilot-instructions.md` and `.github/instructions/**/*.instructions.md` | Same locations and formats | Validate discovery by host and scope | ✅ Baseline |
| Instructions | Workspace | `AGENTS.md`, `CLAUDE.md`, and `GEMINI.md` | Supported formats; validate precedence, nesting, and multi-root behavior | Record sources discovered and applied | 🟡 Baseline; trust-boundary fixes remain for untrusted parents and sibling discovery in [#332700](https://github.com/microsoft/vscode/issues/332700) and [copilot-agent-runtime#16814](https://github.com/github/copilot-agent-runtime/issues/16814) |
| Instructions | User | VS Code profile User Data instructions | Move to `~/.copilot/instructions/**/*.instructions.md` | Record files found and move/copy outcomes | 🟡 User Data migration exists but is not fully rolled out; see [planning #8196](https://github.com/microsoft/vscode-internalbacklog/issues/8196) (internal) |
| Instructions | Workspace or user | Additional paths/globs in `chat.instructionsFilesLocations` | Copilot CLI does not consume the VS Code setting; move to a standard folder or explicitly register supported custom instruction directories | Record configured paths and files found | ⬜ Migration flow needed |
| Skills | Workspace | `.github/skills`, `.agents/skills`, or `.claude/skills` with valid `SKILL.md` | Same folders and Agent Skills format | Validate discovery and activation by host | ✅ Baseline |
| Skills | User | `~/.copilot/skills` or `~/.agents/skills` | Same folders and format | Validate local and remote discovery | ✅ Local baseline; remote provisioning and discovery need validation through [#8196](https://github.com/microsoft/vscode-internalbacklog/issues/8196) (internal), [#316192](https://github.com/microsoft/vscode/issues/316192), and [#316880](https://github.com/microsoft/vscode/issues/316880) |
| Skills | User | `~/.claude/skills` | Supported by VS Code but not listed as a personal Copilot CLI skill location | Record affected users and skills | ❓ Confirm intended compatibility or migrate |
| Skills | Workspace or user | Additional paths in `chat.agentSkillsLocations` | Copilot CLI does not consume the VS Code setting; move to a standard folder or register using Copilot CLI skill management | Record configured paths and skills found | ⬜ Migration or registration flow needed |
| MCP | Workspace | `.vscode/mcp.json` with top-level `servers` | Unsupported by Copilot CLI; convert to `.mcp.json` or `.github/mcp.json` and a supported schema | Record source, servers, conversion result, and servers that require user input | 🟡 Support assessment shipped in [#333051](https://github.com/microsoft/vscode/pull/333051); safe migration for supported servers is in draft in [#333286](https://github.com/microsoft/vscode/pull/333286) |
| MCP | Workspace | `.mcp.json` or `.github/mcp.json` with supported schema | Native Copilot CLI entry point | Validate discovery, authentication, enablement, and invocation across hosts | ✅ Baseline; reliability work includes [duplicate state #330893](https://github.com/microsoft/vscode/issues/330893), [stable identity #330915](https://github.com/microsoft/vscode/issues/330915), [duplicate UI entries #327167](https://github.com/microsoft/vscode/issues/327167), and [authentication in Agents #325081](https://github.com/microsoft/vscode/issues/325081) |
| MCP | User | VS Code profile `mcp.json` | Move or copy to `~/.copilot/mcp-config.json` | Record configured servers and migration result without collecting secrets | ⬜ Decide whether to prompt before copying |
| MCP | Workspace or user | VS Code substitutions such as `${input:...}` or profile-specific values | Determine whether each value can be translated; prompt when secrets or interactive input prevent safe conversion | Record unsupported properties, not values | ❓ Compatibility mapping needed |
| Hooks | Workspace | `.github/hooks/*.json` using Copilot-compatible schema | Same folder; validate `version`, event names, command fields, payloads, and responses | Record files, valid definitions, rejected definitions, and execution host | ✅ Folder baseline; schema validation required |
| Hooks | Workspace or user | Additional files/folders in `chat.hookFilesLocations` | Copilot CLI does not consume the VS Code setting; move to `.github/hooks` or `~/.copilot/hooks` | Record configured paths and definitions found | ⬜ Migration flow needed |
| Hooks | Workspace or user | VS Code/legacy event names and hook definitions | Map to supported Copilot events and input/output semantics | Record incompatible definitions and conversion result | ❓ Compatibility mapping needed |
| Hooks | Workspace or user | `command`, `windows`, `linux`, or `osx` command fields | Convert to portable `command`, `bash`, and/or `powershell` fields where semantics match | Record incompatible fields and conversion result | ⬜ Migration tooling needed |
| Hooks | Workspace or user | Hook definitions that invoke scripts | Validate relative paths, `cwd`, executable bits, shebangs, OS support, and remote availability | Record validation failures without command contents | ⬜ Validation and user guidance needed |
| Tool sets | User | VS Code profile User Data `*.toolsets.jsonc` | No persisted Copilot CLI equivalent is documented | Record files and references, not tool contents | ❓ Decide shared format versus expansion during migration |
| Plugins | Package | Supported `plugin.json` containing agents, skills, hooks, and MCP | Native Copilot CLI plugin format | Validate installation and each component type | ✅ Baseline |
| Plugins | Workspace or user | Local directories in `chat.pluginLocations` | Copilot CLI does not consume the VS Code setting; install through Copilot CLI plugin management | Record registered paths and installation outcome | ⬜ Migration/registration flow needed |
| Plugins | User or organization | `chat.plugins.marketplaces` and `chat.plugins.enabledPlugins` | VS Code marketplace registration and enablement do not automatically transfer to Copilot CLI | Record marketplace/plugin IDs and parity, not credentials | ❓ Decide expected cross-client behavior |
| Plugin slash commands | Package | VS Code/plugin-provided slash-command component | Copilot CLI plugin docs do not list slash commands as a portable component; reusable commands may need to become skills | Record affected plugins and commands | ❓ Compatibility decision needed |
| Parent repository discovery | Workspace | `chat.useCustomizationsInParentRepositories` | Copilot CLI does not consume the setting; compare discovery from an opened subfolder through the repository root for each type | Record setting state and local/AHP discovery differences | ❓ Define and test shared behavior |
| Customization enablement | User or workspace | `chat.useAgentsMdFile`, nested `AGENTS.md`, Claude instructions, skills, hooks, Claude hooks, and agent-scoped hook toggles | Copilot CLI independently discovers and enables supported files; disabled local behavior might become active after migration | Record configured versus effective state | ❓ Decide which enablement state must carry over or be communicated |
| Extension-provided AI contributions | Extension | Chat participants, tools, context providers, and related extension contributions | TBD: determine which contributions remain supported with Agent Host, which require a new SDK path, and which are intentionally retired | Inventory active contributions and effective Agent Host availability | ❓ Scope and ownership discussion needed |

## Progress tracker

| Date | Table change | Evidence |
| --- | --- | --- |
| 2026-08-28 | Workspace and user prompt migration moved from experimental to enabled by default. | [#332262](https://github.com/microsoft/vscode/pull/332262) |
| 2026-08-28 | Workspace MCP migration moved from not started to partially implemented: compatibility assessment shipped and safe migration entered review. | [#333051](https://github.com/microsoft/vscode/pull/333051), [#333286](https://github.com/microsoft/vscode/pull/333286) |
| 2026-08-28 | Workspace instruction discovery moved to partial pending fixes for untrusted parent and sibling-directory discovery. | [#332700](https://github.com/microsoft/vscode/issues/332700), [copilot-agent-runtime#16814](https://github.com/github/copilot-agent-runtime/issues/16814) |
| 2026-08-28 | Shared migration assessment and attention hints landed for consistent entry points from editor chat and the Agents Window. | [#333161](https://github.com/microsoft/vscode/pull/333161), [#333181](https://github.com/microsoft/vscode/pull/333181), [#333216](https://github.com/microsoft/vscode/pull/333216) |

## Definition of done for a migration

- [ ] Detect every legacy entry point before enabling migration broadly.
- [ ] Default to an optional, one-time migration prompt rather than forced or implicit migration.
- [ ] Offer **Migrate**, **Learn more**, and **Skip for now**.
- [ ] Name the source, destination, and operation: move, copy, convert, register, or rewrite.
- [ ] Explain which clients and hosts can use the result.
- [ ] Preserve originals until the migration succeeds or the user explicitly approves removal.
- [ ] Validate the migrated customization in local Agent Host and relevant remote-host scenarios.
- [ ] Add telemetry for detection, offer, accept, success, failure, dismissal, and remaining legacy use.
- [ ] Update public authoring and migration documentation before rollout.
- [ ] Stop directing users toward deprecated folders or formats.
- [ ] Document unsupported capabilities and the recommended replacement.

## Migration UX principles

- **Use the Agent Customizations editor as the migration home.** Sessions, agent and prompt pickers, skills menus, and MCP management can detect an incompatibility and link to it, but migration review and progress should stay in one place.
- **Nudge at the moment of relevance.** Surface migration when a legacy customization is selected, invoked, unavailable in the active host, or approaching deprecation instead of relying on a generic banner.
- **Keep unavailable customizations visible.** Show affected agents, prompts, skills, and other entries as needing migration rather than silently removing them from their usual entry points.
- **Respect ownership.** Personal customizations can offer direct migration. Repository customizations should support generating a plan, filing an issue, or preparing a pull request when the current user is not the maintainer.
- **Use an agent for semantic migrations.** Moving files is insufficient when migration requires rewriting tools, frontmatter, hook definitions, scripts, or MCP configuration. The user should review the proposed changes before they are applied.
- **Validate the result in the target host.** Migration is complete only when the customization is discovered and usable, dependencies resolve, permissions have not broadened, and duplicate legacy and migrated copies are not both active.
- **Make migration resumable and reversible.** Users can skip for now, return later, retry failed validation, and keep the original until the migrated version works.
- **Keep migration knowledge reusable.** Where practical, package migration instructions and deterministic validation scripts as versioned skills or plugins while the product owns detection, orchestration, review, and completion.

## Later / outside the immediate migration

- Long-term synchronization ownership across local machines, remote hosts, cloud environments, and other Copilot surfaces.
- Automatic migration for cases that currently require user review.
- Legacy plugin formats and client-specific plugin components.
- Shared representation for user tool sets.
- Organization-provided customizations and enterprise-managed sources.
- Consolidating temporary compatibility paths after adoption reaches an agreed threshold.

## Measurement

Telemetry should let us answer:

- Which legacy entry points still exist?
- Which supported entry points are discovered by the local harness, Agent Host, and remote hosts?
- Which migrations were offered, accepted, completed, failed, or dismissed?
- Which unsupported fields or formats block migration?
- How many users remain on each legacy entry point after migration ships?

Do not collect customization contents, commands, secrets, MCP input values, or script bodies.

## Open questions

1. Which rows block broader Agent Host adoption and should be addressed first?
2. Should unavailable customizations remain in their existing pickers under a **Needs migration** group?
3. For personal customizations, when should migration move files versus copy them and preserve the originals until validation succeeds?
4. For repository customizations, should the default action apply changes, create a plan, file an issue, or prepare a pull request?
5. Which local enablement decisions must carry over so previously disabled customizations do not become active?
6. Should semantic migration logic ship in the product, in a trusted migration plugin/skills package, or both?
7. What validation is required locally, remotely, or in both places before migration is complete?
8. What are the supported targets for VS Code user tool sets and extension-provided chat participants, tools, and context?

## Related issues

### Planning and workstream tracking

- [#8892 — WS: Customizations Revamped](https://github.com/microsoft/vscode-internalbacklog/issues/8892) (internal)
- [#8195 — Plan prompt-files deprecation and migration](https://github.com/microsoft/vscode-internalbacklog/issues/8195) (internal)
- [#8196 — Plan User Data customizations and local-to-remote forwarding](https://github.com/microsoft/vscode-internalbacklog/issues/8196) (internal)

### Migration implementation and follow-ups

- [#330793 — Test plan: Migrate Customizations to Agent Host Harnesses](https://github.com/microsoft/vscode/issues/330793)
- [#331335 — Migration reports no configured skills folder for the active harness](https://github.com/microsoft/vscode/issues/331335)
- [#328121 — Migration path for existing custom agents](https://github.com/microsoft/vscode/issues/328121)
- [#272734 — Align agent-file tool names](https://github.com/microsoft/vscode/issues/272734)

### Discovery and remote-host gaps

- [#322137 — User-level agents missing in Agent Host](https://github.com/microsoft/vscode/issues/322137)
- [#316192 — Remote skill discovery uses the client path convention](https://github.com/microsoft/vscode/issues/316192)
- [#316880 — Remote Agent Host customization gaps](https://github.com/microsoft/vscode/issues/316880)
- [#321651 — Multi-root folder context with SDK/Agent Host](https://github.com/microsoft/vscode/issues/321651)

### MCP reliability

- [#330893 — Duplicate MCP customization remains in Agent Host state](https://github.com/microsoft/vscode/issues/330893)
- [#330915 — Derive MCP customization identity from ownership](https://github.com/microsoft/vscode/issues/330915)
- [#327167 — Duplicate MCP servers in Agent Customizations](https://github.com/microsoft/vscode/issues/327167)
- [#325081 — Authenticated MCP servers unavailable in the Agents window](https://github.com/microsoft/vscode/issues/325081)

### Measurement

- [#8889 — Missing Agent Host customization-discovery telemetry](https://github.com/microsoft/vscode-internalbacklog/issues/8889) (internal)

## Documentation references

- [VS Code customization overview](https://code.visualstudio.com/docs/agents/concepts/customization)
- [Create and manage agent customizations](https://code.visualstudio.com/docs/agent-customization/overview)
- [GitHub Copilot CLI customization overview](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/overview)
- [GitHub Copilot CLI custom instructions](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-custom-instructions)
- [GitHub Copilot CLI custom agents](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli)
- [GitHub Copilot CLI skills](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-skills)
- [GitHub Copilot CLI hooks](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/use-hooks)
- [GitHub Copilot CLI MCP servers](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers)
- [GitHub Copilot CLI plugins](https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/plugins-creating)

_🤖 Posted by GitHub Copilot on Harald's behalf._