Understand agent customization

AI models have broad knowledge, but that knowledge isn't a substitute for your project's current requirements or your organization's internal practices. Agent customization adapts an agent to your environment by adding persistent context, repeatable workflows, specialized roles, external tools, and deterministic controls.

Focused customizations reduce repeated prompting and corrective work, which can help reduce AI credit usage. Keep guidance relevant because loaded content also consumes space in the model's context window.

This article explains how customization types differ, when they apply, and what they can and can't control. Use it to choose the right building blocks for your workflow. To install, create, and verify a customization, see Customize agents for your workflow.

Customization building blocks

Each customization type contributes something different to the agent's work:

For saved prompts that you invoke explicitly, prompt files are available in Local harness sessions only.

You don't need a customization for a one-time requirement. Add it to the current request instead. When a problem repeats, choose the smallest useful customization.

How customizations combine

Multiple customizations can contribute to the same task. For example, when you ask the agent to add a checkout button:

• Project instructions specify which design-system components and TypeScript conventions to use.
• A component-building skill provides the workflow and templates for creating the component and its tests.
• A configured post-edit hook runs the project's formatter after file edits.

The instructions guide the implementation within the skill's workflow. The hook handles formatting without relying on the agent to remember that step.

Instructions, skills, and custom agents can all contain guidance. Keep shared project conventions in instructions, task-specific steps in skills, and role-specific guidance in custom agents. Avoid repeating the same rules across them, which makes updates harder and can introduce contradictions.

Model-driven vs. deterministic behavior

Model-driven behavior depends on the model interpreting and following guidance. Even when guidance is loaded into context, the model can misunderstand, partially follow, or ignore it. Instructions are not enforcement.

Deterministic behavior is triggered or enforced by harness code, rather than relying on the model to comply. The distinction depends on which part of a customization you use:

For example, an instruction to 'run the formatter after editing' can be ignored. A configured post-edit hook triggers the formatter without relying on the model to remember that instruction.

Deterministic triggering doesn't guarantee success or identical results. Hook execution still depends on discovery, enablement, trust, filters, timeouts, and error handling. Review actual tool and hook activity rather than relying only on the model's response.

Neither instructions nor hooks alone establish a security boundary.

Customization scope

Customization scope describes where a customization is defined or installed and how it is shared. A session can combine personal preferences, project-specific guidance, and organization-wide workflows. Scope alone doesn't determine whether a customization reaches the session or is used for a particular request.

Personal and shared customizations

The same customization type can exist at different scopes, depending on harness support:

• User: defined in a user's configuration and available across workspaces that use it.

• Workspace or repository: stored with the project and shared with contributors through source control.

• Organization: managed centrally and made available across repositories, where supported.

Applicable customizations are additive: personal, project, and organization guidance can apply together. They can also conflict, for example if they require different test frameworks. There is no universal override order across harnesses and customization types.

Repository customizations can be shared and versioned with the project. Personal customizations are stored separately from that project.

Company-shared skills and plugins still need to be installed for the selected harness.

Through managed policies, an organization can enforce limits on tools, MCP servers, and approvals. Customizations can't override those limits. See enterprise AI controls.

Which customizations reach a session

The customizations available to a session depend on its harness, workspace, execution environment, and connected client.

The agent harness determines which customization types, formats, and locations are supported in an agent session. See reusing customizations across harnesses for setup guidance. For example, the Copilot harness stores its configuration in a location shared with other Copilot experiences.

The selected workspace supplies project customizations. The machine (local, remote, or Dev Container) running the harness supplies its native user configuration.

A connected client can supply additional supported customizations. A remote host or container changes where configuration is read, not its scope. Resuming a session from another device preserves its host-owned configuration, but can change the client-supplied customizations. Personal configuration isn't automatically identical across machines or harnesses.

In the following diagram, the frontend session running on the user's workstation receives an organization skill, user instructions and the workspace's instructions and skill. When the user connects remotely to the agent session from another device, the session retains its host-owned configuration while adding the client-supplied customizations from the new device.

The Agent Customizations editor shows discovered customizations for the selected session, including disabled items. See Use the Agent Customizations editor. This means that if you select a different session, the editor displays the customizations relevant to that session, which may differ from the previous one.

When available customizations are used

Enablement controls whether a customization is turned on globally, for a workspace, for a harness, or for a session, where those choices are supported. It doesn't change where the customization is stored.

Even when enabled, a customization isn't necessarily used for every request. Always-on instructions are included in each request, while conditional instructions depend on matching files or tasks. A skill is loaded when invoked or selected, and a tool is called when needed.

Editing a shared definition can affect other sessions that read it, even when the edit starts from one session's customization editor. See what a change affects.

Marketplaces and reusable customizations

You don't need to author every customization yourself. Marketplaces help you discover existing workflows and integrations from community publishers or your organization.

Plugin marketplaces are catalogs of plugins. Adding a marketplace makes its plugins available to browse. Installing a plugin makes its supported customizations available to your harness.

The Customization Marketplace in VS Code is the unified browse experience in the Agent Customizations editor (Preview). It brings together supported sources, including plugin marketplaces, GitHub Feed, and Copilot connectors Copilot connectors is in preview and might change before it becomes generally available. . Some sources offer individual skills or MCP servers; others offer plugins that bundle customizations. Available sources depend on the harness and organization policy.

A marketplace is a discovery and distribution mechanism, not another customization type. Installed components keep their own activation rules. Review the publisher, included files, and setup requirements before installation, then test the result in your workflow. See Discover and install existing customizations.

Related resources

• Customize agents for your workflow
• Configure AI for your codebase