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.

Agent Customizations editor

The Agent Customizations editor provides a central place to discover, create, and manage customizations. It organizes customization types into separate tabs and includes an editor with syntax highlighting and validation.

When you open the Customizations editor, the customizations are scoped to the selected agent harness. 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:

Create a customization

You can create customization files manually or use AI to generate them, after which you can further edit them.

Create a customization with AI

You can create a customization file with AI assistance. To do this, open the Agent Customizations editor and enter a prompt in the Overview tab that describes what you want to create. The agent asks for any missing details and generates the customization in the appropriate format.

For example, to create a code reviewer skill, you can enter the following prompt:

Code reviewer skill that checks for code style, best practices, and potential bugs in Python and JavaScript files.

Create a customization manually

You can manually create a customization file by using the Chat: New <customization-type> command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)). This creates the corresponding file in the appropriate location for the selected customization type. You can then edit the file in the inline editor or in a separate editor tab.

Alternatively, you can use the Agent Customizations editor to create a customization file. Follow these steps:

1. Open the Agent Customizations editor and select a customization type

2. Choose between creating a user or workspace customization from the New dropdown

3. Enter a name and choose a storage location when prompted

4. An inline editor opens where you can further edit the customization file. The editor provides syntax highlighting and validation for the customization type.

For MCP servers and agent plugins, browse the corresponding marketplace from the editor, install an item, and manage the installation from the same tab.

See the guide for each customization type for its file format and configuration options.

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.

Some customization types support other scopes, such as organization-level instructions. Not every customization type supports every scope. See the individual guide for its supported locations.

Migrate customizations (Experimental)

Agent Host sessions load customizations from supported folders and don't use some VS Code-specific formats and locations. The Agent Customizations editor provides separate migrations for each type of incompatibility.

A migration card appears only when you select an Agent Host, the corresponding setting is enabled, and VS Code finds customizations to migrate.

Migrate prompt files to skills

Prompt file migration is enabled by default. It converts both workspace and user prompt files to skills.

To migrate prompt files:

1. In the Chat view, select the Agent Host that should use the skills.

2. Select Configure Chat (gear icon) to open the Agent Customizations editor.

3. On the Overview tab, find Migrate Prompt Files and select Convert to Skills....

4. Select the prompt files to convert. You can open a file to review it before migration.

5. Select Convert to Skills.

6. In the confirmation dialog, choose whether to delete the original prompt files, and then select Convert to Skills.

Review any migrated skills that used prompt file frontmatter properties that aren't supported by skills. If you keep the original prompt files, the prompts and migrated skills don't stay synchronized.

Migrate user customizations

Agents that run through Agent Host don't read custom agents and instructions stored in your VS Code profile user data. The migration flow copies these customizations to the user folders for the selected Agent Host without changing their names, types, or contents.

The migrated files don't roam across devices through Settings Sync. If you keep the original files in your profile user data, the original and migrated copies don't stay synchronized.

To migrate user customizations:

1. Enable the chat.customizations.userDataMigration.enabled Open in VS Code Open in VS Code Insiders setting.

2. In the Chat view, select the Agent Host that should use the customizations.

3. Select Configure Chat (gear icon) to open the Agent Customizations editor.

4. On the Overview tab, find Migrate User Data Customizations and select Migrate....

5. Select the agents and instructions to migrate. You can open a file to review it before migration.

6. Select Migrate.

7. In the confirmation dialog, choose whether to delete the original files from your profile user data, and then select Migrate.

Migrate customizations from configured locations

The chat.agentFilesLocations Open in VS Code Open in VS Code Insiders , chat.modeFilesLocations Open in VS Code Open in VS Code Insiders , chat.instructionsFilesLocations Open in VS Code Open in VS Code Insiders , and chat.agentSkillsLocations Open in VS Code Open in VS Code Insiders settings configure additional locations for the Local agent. These settings are deprecated because Agent Host sessions don't use them.

To migrate customizations from these locations:

1. Enable the chat.customizations.locationsMigration.enabled Open in VS Code Open in VS Code Insiders setting.

2. In the Chat view, select the Agent Host that should use the customizations.

3. Select Configure Chat (gear icon) to open the Agent Customizations editor.

4. On the Overview tab, find Migrate Location Settings and select Migrate....

5. Select the custom agents, instructions, and skills to migrate. You can open a file to review it before migration.

6. Choose whether to clear the unused location settings after migration. This option is selected by default.

7. Select Migrate.

8. In the confirmation dialog, choose whether to delete the original files, and then select Migrate.

Clearing a location setting and deleting its original files are separate choices. If you keep the original files, the original and migrated copies don't stay synchronized.

Prompt files in locations configured with chat.promptFilesLocations Open in VS Code Open in VS Code Insiders aren't included in this migration. Use prompt file migration to convert them to skills.

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 extension helps you catch these problems before you rely on a customization, by analyzing your files and suggesting concrete improvements.

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 (⇧⌘P (Windows, Linux Ctrl+Shift+P)). 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 (⇧⌘M (Windows, Linux Ctrl+Shift+M)) with line and column locations. After the analysis completes, select Implement Suggestions to apply the suggested improvements.

For skill files, the extension integrates with the 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.

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 chat.useCustomizationsInParentRepositories Open in VS Code Open in VS Code Insiders 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:

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. VS Code prompts you to trust the parent folder when the workspace is opened.

Troubleshoot customization issues

If your customizations aren't being applied or cause unexpected behavior, open the Agent Debug Logs panel to troubleshoot agent issues. Run Developer: Open Agent Debug Panel from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)), or in the Chat view select the ellipsis (...) menu and select Show Agent Debug Logs.

Related resources

• Customization concepts
• Customize AI for your project guide