Skip to content

By using VS Code, you agree to its license and privacy statement. By using VS Code, you agree to License & Privacy.

Customize agents for your workflow

Agent customizations adapt agents to your coding standards, workflows, and development systems. Start by looking for an existing skill, plugin, or integration in a customization marketplace before creating your own. This guide helps you find, install, and verify customizations in Visual Studio Code, or create project-specific guidance. To understand how customization types differ and work together, see Agent customization concepts.

Choose how to customize

Start with a recurring task or an observed problem, such as the agent using the wrong test command. Choose a representative task and define the result you expect. If the agent already meets your needs, don't add a customization. Put one-time requirements in the current request instead.

If you want to Start with
Adopt an existing workflow or packaged setup Browse customization marketplaces for skills, plugins, and integrations
Stop repeating project commands and conventions Create or refine project instructions
Reuse a multi-step process specific to your team Create or adapt an agent skill
Give a recurring role focused guidance and tools Create a custom agent
Connect an external service Use a Copilot connector Copilot connectors is in preview and might change before it becomes generally available. or add an MCP server
Run an action at specific events of the agent's workflow Configure a hook

Reuse or adapt an existing customization before creating one from scratch. You can combine approaches, such as installing a plugin and adding project instructions. For saved prompts and a comparison of all the options, see customization types and activation.

For a complete project walkthrough, follow Configure AI for your codebase.

Check harness compatibility

An agent harness coordinates the model, tools, and customizations for a session. It determines which customization formats and locations are supported. Choosing a different language model doesn't change those requirements.

Before installing, copying, or creating a customization:

  1. Select the intended harness from the Session Target control in a new chat.

  2. Open the Agent Customizations editor for that harness, as described below.

  3. Follow the guide for your customization type for the harness-specific file location, fields, and activation rules.

Note

Prompt files and tool sets require a Local harness session in the Chat view. Local sessions aren't available in the Agents window. For reusable workflows in other skills-compatible harnesses, use a skill instead of a prompt file.

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 without committing it to the project.

  • Workspace: share project guidance and workflows with contributors through source control.

  • Organization: centrally manage supported customization types across repositories. Configure these through GitHub rather than the Agent Customizations editor.

Not every customization type supports every scope. User files must be stored in a location supported by the harness on the machine where the agent runs, and aren't shared automatically between machines. Follow the individual customization guide for supported locations.

Agent Customizations editor

The Agent Customizations editor provides a central place to discover, create, and manage customizations for the selected harness. It organizes customization types into separate sections, with configuration forms, inline file editors, or read-only details depending on the type and source.

Follow these steps to open the Agent Customizations editor:

In the left sidebar, select Customizations to open the Agent Customizations editor. Then select the customization type in the editor.

Screenshot showing the Customizations sidebar action and the Agent Customizations editor.

The experimental Extensions section also lets you choose which installed extensions run in the Agents window.

Open customization pages with deep links

You can also use chat-customizations/open URLs to navigate directly to a specific section in the Agent Customizations editor:

vscode://chat-customizations/open?page=<page>&search=<query>

Parameters:

  • page (required): The customization section to open. Supported values include:
    • discover: Opens the Customization Marketplace (Browse page). Requires chat.customizations.marketplace.enabled Open in VS Code Open in VS Code Insiders .
    • agents: Opens the Custom Agents section.
    • skills: Opens the Agent Skills section.
    • instructions: Opens the Custom Instructions section.
    • hooks: Opens the Hooks section.
    • mcp-servers: Opens the MCP Servers section (also accepts mcp-server).
    • plugins: Opens the Agent Plugins section.
    • tools: Opens the Tools section.
    • migrations: Opens the Migrations review view.
  • search (optional): A search query to pre-populate in the section's search field. URL-encode query values.

These links navigate within the selected harness context; they do not install customizations or bypass consent, workspace trust, or enterprise policies.

Examples:

  • Open the plugins section:

    vscode://chat-customizations/open?page=plugins

  • Open skills filtered to "python":

    vscode://chat-customizations/open?page=skills&search=python

  • Open the Discover marketplace:

    vscode://chat-customizations/open?page=discover
Note

For VS Code Insiders, use the vscode-insiders:// scheme instead of vscode://. To share links on web pages or markdown badges, use the HTTPS redirect wrapper: https://vscode.dev/redirect?url=<url-encoded-vscode-URL>. For more information on URL handlers, see URL handling.

Discover and install existing customizations (Preview)

Use the Customization Marketplace to find a workflow or integration you can reuse instead of building it from scratch. The unified Browse page brings together available sources, including plugin marketplaces, GitHub Feed, and Copilot connectors Copilot connectors is in preview and might change before it becomes generally available. . Available sources and installation actions depend on the selected harness and organization policy.

You can install an individual skill or a plugin that bundles related customizations, such as skills, custom agents, hooks, and MCP servers. For a service integration, find an MCP server or connect a supported service without server setup.

To find and install a customization:

  1. Open the Agent Customizations editor and select Browse.
  2. Use the source menu to browse all sources or select a specific available source, such as GitHub Feed or an individual plugin marketplace.
  3. Search by name or use a type filter, such as @type:skill or @type:mcp.
  4. Select an item and review its publisher, source, installation details, and any setup requirements.
  5. Select Install and choose a destination when prompted. For Copilot connectors Copilot connectors is in preview and might change before it becomes generally available. , select Connect and complete authorization instead.

Some items are available for discovery but don't support automatic installation. Follow the publisher's setup instructions when they are provided.

If your team shares plugins through another marketplace, select Configure Marketplaces from the source menu to add or manage plugin marketplaces. Adding a marketplace makes its plugins available to browse. It doesn't install them.

After installation, complete any publisher setup and verify the customization with a representative task. For type-specific guidance, see install a skill, install a plugin, or find an MCP server.

Marketplace availability

The Browse page appears when a marketplace source is available. Marketplace discovery is enabled by default with chat.customizations.marketplace.enabled Open in VS Code Open in VS Code Insiders .

If Browse isn't available, check that the setting is enabled and your organization permits Editor preview features. Disabling that policy forces the unified Browse experience and Copilot connectors off. See organization and enterprise settings.

The experimental GitHub Feed source is enabled by default for harnesses that provide marketplace search. Local sessions don't provide this source, and organization policy can restrict access. Use the chat.customizations.marketplace.sources.publicFeed.enabled Open in VS Code Open in VS Code Insiders setting to show or hide this source. For plugin discovery without the unified Browse page, follow the plugin installation guide.

Create a customization

For file-based customizations, use the editor to create a file in the chosen scope:

  1. Open the Agent Customizations editor and select a customization type.
  2. Select the + button next to Workspace to share the customization with your project, or next to User to use it across your workspaces.
  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.

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, see Add MCP servers. To update an existing connection, see Edit an MCP server configuration.

Creating or saving a file doesn't establish that the agent uses it. Verify the customization before relying on it or sharing it with your team.

Verify a customization

Repeat your representative task in a fresh chat with the intended harness and workspace. Don't repeat the customization's rules in the test prompt. Check these three stages separately:

  1. Discovery: open the Agent Customizations editor and confirm that the customization is listed without validation errors.
  2. Inclusion or invocation: check whether the request uses the customization. For instructions and skills, inspect the response's References section, where available, or Agent Debug Logs. For tools and hooks, inspect the corresponding tool activity or execution logs.
  3. Effectiveness: review the changes, commands, and results against the outcome you defined. Inclusion doesn't guarantee that the agent follows the guidance.

For example, if project instructions specify the correct test command, ask the agent to make a small code change without restating that command. Confirm that it runs the expected tests and reports their results.

If a stage fails, troubleshoot that stage before adding more guidance. Once the customization meets your goal, review it before sharing it. For a complete before-and-after workflow, see Configure AI for your codebase.

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.
  4. 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.

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 for detailed steps.

Troubleshoot customization issues

Use the verification result to choose your next action:

Symptom What to check
The customization isn't listed Confirm the harness, file name, and supported location. Ensure the session uses the folder containing your changes.
The customization has validation errors Correct the reported file or configuration errors.
It's discovered but isn't included or invoked Check activation conditions against the current file or task. Invoke an on-demand customization explicitly when supported.
It's included but doesn't improve the result Resolve conflicting guidance, make vague rules more specific, and repeat the task in a fresh chat.

For hooks, also verify the script's event inputs and outputs. Hooks in user folders, settings, repositories, custom agents, and plugins can require manual migration to the shared Copilot runtime, even when the file is discovered.

If the issue continues, follow customization diagnostics and agent troubleshooting.

Advanced scenarios

Repair marketplace installations

If a Marketplace-installed skill shows Missing files, select Repair to restore only the missing files. Repair preserves files that you edited or added. Installed indicates that the recorded target is available.

A Marketplace-installed customization and a local customization with the same name remain separate. Deleting the Marketplace installation doesn't remove the unrelated local customization.

Manage canvas extensions

The Canvases section lists canvas extensions available to the active local Copilot session and groups them by source. For prerequisites, opening canvases, and managing extension enablement, see Use canvases with agents.

Use customizations in a monorepo

In monorepo setups, you might open a subfolder of a repository rather than the repo root. For Local harness discovery, enable chat.useCustomizationsInParentRepositories Open in VS Code Open in VS Code Insiders to also discover customizations from the parent repository. Other harnesses use their own discovery rules. See nested project instructions.

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.
Note

The chat.useCustomizationsInParentRepositories Open in VS Code Open in VS Code Insiders setting is disabled by default.

Evaluate and improve customization files (Preview)

For larger customization collections, the separately published Chat Customizations Evaluations extension analyzes skills, custom agents, instructions, and prompt files for ambiguity, contradictions, and overly complex rules.

After installing the extension, open a customization file and run Chat Customizations Evaluations: Analyze from the Command Palette (⇧⌘P (Windows, Linux Ctrl+Shift+P)). Review the diagnostics in the Problems panel (⇧⌘M (Windows, Linux Ctrl+Shift+M)) before selecting Implement Suggestions.

For analysis guidance and skill evaluations with Waza, run Chat Customizations Evaluations: Open Analysis and Fix User Guide. File analysis complements, but doesn't replace, testing the customization on a representative task.

Related resources

11/4/2026