skills.rest
microsoft
microsoftOFFICIAL
Explore all skills by this author →
Website𝕏@OpenAtMicrosoftGitHub

customizations-in-the-agent-host

Diagnose and fix customization enablement bugs in the VS Code agent host.

190k|41.9k|Updated Sep 3, 2015
Search Tags:#Debugging#VSCode#MCP-servers#agent-host#provider-sdk#customization-enablement#cross-session-persistence
One-click install
npx skills add https://github.com/microsoft/vscode --skill customizations-in-the-agent-host
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: customizations-in-the-agent-host
Source: https://github.com/microsoft/vscode/tree/main/.github/skills/customizations-in-the-agent-host
Command: npx skills add https://github.com/microsoft/vscode --skill customizations-in-the-agent-host

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Customizations (plugins, MCP servers, agents, skills, instructions) in the VS Code agent host frequently show the wrong enabled state, persist decisions incorrectly across sessions, or leak disabled servers to the model. This Skill provides the mental model, invariants, and debugging playbook needed to fix these issues without introducing new ones.

Core Features & Use Cases

  • Enablement Architecture: Explains the scoped decision list (Session/Workspace/Global), the overlay model where host decisions layer on top of client values, and the ownership rules for Global decisions.
  • Identity & Storage Rules: Covers how MCP server keys must be derived from owningPluginUri rather than tree position, and why pending enablement must fail closed without being cached.
  • Provider Enforcement Differences: Documents how Copilot, Claude, and Codex differ in launch-time vs mid-session enforcement, including the documented Codex limitation that MCP servers can only be supplied at thread/start.
  • Debugging Playbook: Ranks signals (published object > tool_search log > UI > model claims), provides a reproduction recipe that exercises cross-session persistence, and lists known false alarms like the azure plugin's 24 skills.

Quick Start

Read this skill before modifying agentHostCustomizationEnablementService.ts, the customization enablement gate, or any per-provider customization path, then run the validation commands listed in the Validation section.

Frequently Asked Questions about customizations-in-the-agent-host

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I fix a disabled MCP server that still reaches the model in VS Code agent host?▼

Route every publication, emit, and SDK-handoff path through `resolveCustomizationEnablement()` instead of reading a stored snapshot. Gate at launch as well as the post-startup reconcile, and never translate the SDK's `not_configured` status as `enabled: true`.

Why does a customization's enabled state show incorrectly in the UI?▼

The UI reads from `_persistent`, which holds only host-owned decisions that differ from the client's base. If `_setClientGlobal` writes to `_persistent` instead of `_clientGlobalEnablement`, the overlay model breaks and decisions get silently erased.

What is the difference between Session, Workspace, and Global enablement scopes?▼

Session applies to the current session only, Workspace applies to the working directory and carries a URI, and Global applies everywhere. `isCustomizationEnabled()` picks the first entry from the ordered list, and absent entries inherit from the next scope out.

Can Codex disable MCP servers mid-session in the agent host?▼

No. Codex only accepts MCP servers at `thread/start` or resume, so mid-session disable is not possible. This is a documented limitation; Copilot uses `rpc.mcp.enable`/`rpc.mcp.disable` and Claude uses live reconcile for mid-session changes.

How do I prevent cross-session persistence bugs for MCP server enablement?▼

Derive the storage key from `owningPluginUri` using `targetForMcpServer()` and `withOwningPluginUri()` in the gate. The same server discovered top-level and nested under a plugin must produce one key, or decisions written in one session become invisible to the next.

Related Skills

Explore More Software Engineering Skills→
thmtzthmtz
5

add-atomic-chat-tool

Deploy a stdio-based MCP server to expose Atomic Chat model tools to container agents.

Community
Advanced
NostoNosto

repo-workflow

Automate repository validation and commit hygiene with lint, typecheck, tests, and conventional commits.

Official
Intermediate
n0ann0an
103

start-logs-device

Launch VivaDicta on a physical iOS device with print logging enabled.

Community
Intermediate
buvisbuvis
2

audit-settings

Audit global, project, and local CLAUDE settings for conflicts and overrides.

Official
Intermediate