> AI agents: For documentation discovery and navigation, see [llms.txt](/llms.txt).
# Create and manage agent customizations
Agent customizations adapt agents to your coding standards, workflows, and development systems. This article explains how to create, manage, evaluate, and troubleshoot customizations in Visual Studio Code. To compare the customization types and understand how they work together, see [Agent customization concepts](/docs/agents/concepts/customization.md).
Learn about the different customization types and when to use each one.
* [Customization concepts](/docs/agents/concepts/customization.md)
Follow a hands-on walkthrough to customize AI for your project.
* [Customize AI for your project](/docs/agents/guides/customize-copilot-guide.md)
## Agent Customizations editor
The Agent Customizations editor provides a central place to discover, create, and manage customizations. It organizes customization types into separate sections. Depending on the customization type and source, it provides a configuration form, an inline file editor with syntax highlighting and validation, or a read-only details view.
When you open the Customizations editor, the customizations are scoped to the selected [agent harness](/docs/agents/concepts/agent-harnesses.md). Select the harness from the dropdown in the chat input before you open the editor to ensure the customizations apply to the correct context.
Follow these steps to open the Agent Customizations editor:
{% tabs id="chat-surface" %}
{% tab label="Agents window" %}
In the left sidebar, select a customization type in the **Customizations** panel.
{% /tab %}
{% tab label="Chat view" %}
In the Chat view, select the **Configure Chat (gear icon)** or run **Chat: Open Customizations** from the Command Palette (`kb(workbench.action.showCommands)`).
{% /tab %}
{% /tabs %}
### Discover marketplace customizations (Experimental)
The Customization Marketplace provides a unified **Discover** page for finding skills, MCP servers, plugins, and other agent customizations from configured sources. To use the marketplace, turn on the `setting(chat.customizations.marketplace.enabled)` setting.
The GitHub Feed source is available by default when the marketplace is enabled. Use the `setting(chat.customizations.marketplace.sources.publicFeed.enabled)` setting to show or hide this source.
To find and install a customization:
1. Open the Agent Customizations editor and select **Discover**.
1. Use the source menu to browse all sources or select a specific source, such as **GitHub Feed**.
1. Search by name or use a type filter, such as `@type:skill` or `@type:mcp`.
1. Select an item and review its publisher, source, installation details, and any setup requirements.
1. Select **Install** and choose a destination when prompted.
Some items are available for discovery but don't support automatic installation. Follow the publisher's setup instructions when they are provided.
Marketplace items show a source or publisher image in **Discover** and, when available, on the installed item and its details page. Use this information together with the item details to verify the source before installation.
VS Code associates marketplace state with the exact installed target, not only its display name. A local customization and a Marketplace-installed customization with the same name remain separate:
* **Installed** indicates that the recorded target is available.
* **Missing files** indicates that files from a Marketplace-installed skill are no longer present. Select **Repair** to restore only the missing files. Repair preserves files that you edited or added.
* Deleting a Marketplace-installed customization removes its exact installation. It doesn't remove an unrelated local customization with the same name.
## Choose a customization scope
Store a customization at the narrowest scope that matches how you want to use and share it:
* **User**: use the customization across your workspaces. User customizations are specific to you and are not committed to the project.
* **Workspace**: share the customization with project contributors through source control.
* **Organization**: centrally manage supported customization types and share them across repositories. Organization customizations are configured through GitHub rather than created in the Agent Customizations editor.
Scope determines where a customization is available and who can share it. Not every customization type supports every scope. The selected agent harness also determines which customization types and locations it supports. See the guide for each customization type for its supported locations.
> [!NOTE]
> Store user-level customizations in a folder that the selected harness supports on the machine where the agent runs. For example, Copilot reads customizations from `~/.copilot`, and Anthropic Claude reads them from `~/.claude`. These folders are separate from your VS Code profile user data and aren't shared automatically between machines. See [instructions](/docs/agent-customization/custom-instructions.md#instructions-file-locations), [custom agents](/docs/agent-customization/custom-agents.md), and [prompt files](/docs/agent-customization/prompt-files.md#prompt-file-locations) for supported user-level locations.
## Create a customization
You can create customization files with AI or create them manually. Review and test every customization before you rely on it for development tasks.
### Create a customization with AI
1. Open the Agent Customizations editor.
1. In the **Overview** section, enter a prompt that describes what you want to create.
1. Answer any questions the agent asks about missing details.
1. Review the generated customization, correct any inaccurate information, and save the file.
For example, to create a code reviewer skill, you can enter the following prompt:
```prompt
Create a workspace code reviewer skill for Python and JavaScript files. Check the code against the conventions in this repository, identify correctness and maintainability issues, and report findings with file locations and suggested fixes.
```
### Create a customization manually
1. Open the Agent Customizations editor and select a customization type.
1. From the **New** dropdown, choose a user or workspace customization.
1. Enter a name and choose a storage location when prompted.
1. Edit the customization in the inline editor, which provides syntax highlighting and validation.
1. Review and save the customization.
You can also run the **Chat: New \** command from the Command Palette (`kb(workbench.action.showCommands)`). The command creates the corresponding file in a supported location for that customization type.
To add an MCP server manually, select **MCP Servers**, select **Add Server** (**+**) in the **User** or **Workspace** group, and follow the guided flow. For detailed steps and configuration options, see [Add and manage MCP servers](/docs/agent-customization/mcp-servers.md#add-a-server-from-the-agent-customizations-editor).
For Agent Skills, MCP servers, and agent plugins, use [Discover](#discover-marketplace-customizations-experimental) to browse marketplace sources and install an item. Manage the installation from the corresponding section.
See the guides for [custom instructions](/docs/agent-customization/custom-instructions.md), [agent skills](/docs/agent-customization/agent-skills.md), [prompt files](/docs/agent-customization/prompt-files.md), [custom agents](/docs/agent-customization/custom-agents.md), [MCP servers](/docs/agent-customization/mcp-servers.md), [hooks](/docs/agent-customization/hooks.md), and [agent plugins](/docs/agent-customization/agent-plugins.md) for their file formats and configuration options.
## Manage existing customizations
Use the Agent Customizations editor to find and update customizations for the selected harness:
1. Open the Agent Customizations editor and select the customization type.
1. Use the search box to find the customization.
1. Select the customization to open its details.
1. If the customization is editable, update its form or file and save your changes. For a read-only customization, use the available action to open the source file.
The available actions depend on the customization type and its source. Use the inline actions or context menu to access supported operations, such as revealing an editable file in your operating system or deleting it. Manage plugin-provided customizations from the **Plugins** section.
`feature(user-customization-migration)`
> [!IMPORTANT]
> If the Agent Customizations editor shows **Migrations**, Copilot cannot use one or more customizations in their current location or format. Select **Migrations** to review the required work, and follow [Migrate Copilot customizations in VS Code](/docs/agent-customization/migrate-customizations.md) for detailed steps.
## Verify a customization
Test a new or updated customization with a representative task. Check that the agent follows the expected instructions, workflow, tool configuration, or lifecycle action. For instructions and skills, expand the **References** section in the chat response to confirm that the expected customization was included.
If the result doesn't match your intent, make the customization more specific, resolve conflicting guidance, and repeat the task. For a complete project workflow, including how to review and share generated instructions, see [Configure AI for your codebase](/docs/agents/guides/customize-copilot-guide.md).
## Troubleshoot customization issues
If a customization isn't applied or causes unexpected behavior, check the following:
* The intended agent harness is selected.
* The customization is stored in a location that the harness supports.
* Any activation conditions match the current file or task.
* The customization file has no validation errors.
If the issue continues, open the **Agent Debug Logs** view to [troubleshoot agent issues](/docs/agents/agent-troubleshooting/troubleshooting.md). Run **Developer: Open Agent Debug Logs** from the Command Palette (`kb(workbench.action.showCommands)`), or in the Chat view select the ellipsis (**...**) menu and select **Show Agent Debug Logs**.
## Use customizations in a monorepo
In monorepo setups, you might open a subfolder of a repository in VS Code rather than the repo root. By default, VS Code only discovers customization files within your open workspace folder(s). Enable the `setting(chat.useCustomizationsInParentRepositories)` setting to also discover customizations from the parent repository.
When this setting is enabled, VS Code walks up the folder hierarchy from each workspace folder until it finds a `.git` folder. If found, it collects customizations from all folders between the workspace folder and the repository root (inclusive). This applies to all customization types: always-on instructions (`copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`), file-based instructions, prompt files, custom agents, agent skills, and hooks.
For example, consider the following monorepo structure:
```text
my-monorepo/ # repo root (has .git folder)
├── .github/
│ ├── copilot-instructions.md
│ ├── instructions/
│ │ └── style.instructions.md
│ ├── prompts/
│ │ └── review.prompt.md
│ └── agents/
│ └── reviewer.agent.md
├── packages/
│ └── frontend/ # opened as workspace folder
│ └── src/
```
If you open only `packages/frontend/` in VS Code and enable the setting, VS Code discovers the customization files at the repo root, such as `copilot-instructions.md`, `style.instructions.md`, `review.prompt.md`, and `reviewer.agent.md`.
Conditions for parent repository discovery:
* The workspace folder does not contain a `.git` folder (it is not itself a repository root).
* A parent folder contains a `.git` folder.
* The parent repository folder is [trusted](/docs/editing/workspaces/workspace-trust.md). VS Code prompts you to trust the parent folder when the workspace is opened.
> [!NOTE]
> The `setting(chat.useCustomizationsInParentRepositories)` setting is disabled by default.
## Evaluate and improve customization files (Preview)
As your collection of customization files grows, it can be hard to tell whether they actually guide the AI the way you intend. Vague wording, contradictory rules, or overly complex instructions can degrade results. The [Chat Customizations Evaluations](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-chat-customizations-evaluations) extension helps you catch these problems before you rely on a customization, by analyzing your files and suggesting concrete improvements.
> [!NOTE]
> The Chat Customizations Evaluations extension is published separately from VS Code. Install it from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=ms-vscode.vscode-chat-customizations-evaluations).
The extension works with skill files (`SKILL.md`), custom agent files (`*.agent.md`), instructions files (`*.instructions.md`), and prompt files (`*.prompt.md`).
Open a customization file and run the **Chat Customizations Evaluations: Analyze** command from the Command Palette (`kb(workbench.action.showCommands)`).
The extension uses GitHub Copilot to detect issues such as:
* Logical, behavioral, and format contradictions
* Ambiguous wording, with suggested rewrites
* Conflicting persona traits and tone drift
* Excessive cognitive load from deeply nested conditions
* Gaps in intent handling and missing error paths
* Conflicts between a file and other customization files it links to
Diagnostics appear in the **Problems** panel (`kb(workbench.actions.view.problems)`) with line and column locations. After the analysis completes, select **Implement Suggestions** to apply the suggested improvements.
> [!TIP]
> You can also start an analysis from chat with the `/analyze-prompt` slash command, which summarizes the diagnostics for the active customization file directly in the Chat view.
For skill files, the extension integrates with the [Waza](https://github.com/microsoft/waza) evaluation framework to measure how well a skill performs against a set of test cases. Run **Chat Customizations Evaluations: Download Waza Binary** to install Waza, **Chat Customizations Evaluations: Create Waza Eval Scaffold** to generate evaluation files for the active skill, and **Chat Customizations Evaluations: Run Waza Evaluation** to run the suite. For step-by-step guidance, run **Chat Customizations Evaluations: Open Analysis and Fix User Guide**.
## Related resources
* [Customization concepts](/docs/agents/concepts/customization.md)
* [Customize AI for your project guide](/docs/agents/guides/customize-copilot-guide.md)