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 sections 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:

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.

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.
2. In the Overview section, enter a prompt that describes what you want to create.
3. Answer any questions the agent asks about missing details.
4. 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:

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.
2. From the New dropdown, choose a user or workspace customization.
3. Enter a name and choose a storage location when prompted.
4. Edit the customization in the inline editor, which provides syntax highlighting and validation.
5. Review and save the customization.

You can also run the Chat: New <customization-type> command from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)). The command creates the corresponding file in a supported location for that 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 section.

See the guides for custom instructions, agent skills, prompt files, custom agents, MCP servers, hooks, and agent plugins 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.
2. Use the search box to find the customization.
3. Select the customization to open its details or edit its file.
4. Review and save your changes.

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.

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.

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. Run Developer: Open Agent Debug Logs 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.

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.

Migrate customizations

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.

Related resources

• Customization concepts
• Customize AI for your project guide