Track customization migration readiness for Agent Host

[digitarald]

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 and test plan #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
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 (internal), missing user agents #322137, and migration failure #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; prior naming alignment in #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 and copilot-agent-runtime#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 (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 (internal), #316192, and #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; safe migration for supported servers is in draft in #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, stable identity #330915, duplicate UI entries #327167, and authentication in Agents #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
2026-08-28	Workspace MCP migration moved from not started to partially implemented: compatibility assessment shipped and safe migration entered review.	#333051, #333286
2026-08-28	Workspace instruction discovery moved to partial pending fixes for untrusted parent and sibling-directory discovery.	#332700, copilot-agent-runtime#16814
2026-08-28	Shared migration assessment and attention hints landed for consistent entry points from editor chat and the Agents Window.	#333161, #333181, #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 (internal)
• #8195 — Plan prompt-files deprecation and migration (internal)
• #8196 — Plan User Data customizations and local-to-remote forwarding (internal)

Migration implementation and follow-ups

• #330793 — Test plan: Migrate Customizations to Agent Host Harnesses
• #331335 — Migration reports no configured skills folder for the active harness
• #328121 — Migration path for existing custom agents
• #272734 — Align agent-file tool names

Discovery and remote-host gaps

• #322137 — User-level agents missing in Agent Host
• #316192 — Remote skill discovery uses the client path convention
• #316880 — Remote Agent Host customization gaps
• #321651 — Multi-root folder context with SDK/Agent Host

MCP reliability

• #330893 — Duplicate MCP customization remains in Agent Host state
• #330915 — Derive MCP customization identity from ownership
• #327167 — Duplicate MCP servers in Agent Customizations
• #325081 — Authenticated MCP servers unavailable in the Agents window

Measurement

• #8889 — Missing Agent Host customization-discovery telemetry (internal)

Documentation references

• VS Code customization overview
• Create and manage agent customizations
• GitHub Copilot CLI customization overview
• GitHub Copilot CLI custom instructions
• GitHub Copilot CLI custom agents
• GitHub Copilot CLI skills
• GitHub Copilot CLI hooks
• GitHub Copilot CLI MCP servers
• GitHub Copilot CLI plugins

🤖 Posted by GitHub Copilot on Harald's behalf.