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.

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.

How customization changes an agent

The model brings general knowledge learned during training. The agent combines that knowledge with your prompt, the current conversation, and available context, such as workspace files. Your organization's internal practices and information in other projects aren't automatically available. Customizations provide reusable guidance and access to additional capabilities, so you don't have to supply the same context in every prompt.

Different mechanisms change different parts of the agent's work. Instructions and workflows guide the model's decisions. Tools expand the actions it can take. Hooks run commands at specific points in the agent's workflow, such as before or after a tool runs, without relying on the model to request them. Plugins package related customizations for installation and sharing.

Adding a rule to an instructions file is not equivalent to executing a validation script. Neither mechanism alone establishes a security boundary.

Relevant customizations can reduce back-and-forth and rework by giving the agent project context from the start. Avoiding corrective turns and discarded implementations can help reduce AI credit usage. Keep customizations focused because their content also consumes space in the model's context window.

Customization options at a glance

Customization types differ in both purpose and activation. Activation determines when guidance enters a request or an action runs. Support depends on the agent harness, the runtime that coordinates the model and tools, rather than the language model you select.

The closest alternatives differ in these ways:

• Instructions or skills: instructions provide standing guidance, such as project conventions. A skill describes how to perform a particular task and can include scripts, templates, and other resources.
• Skills or prompt files: a skill can be discovered for a relevant task or invoked directly. A prompt file is a saved prompt that you invoke explicitly in a Local harness session.
• Skills or custom agents: a skill supplies a workflow. A custom agent defines the role and tool configuration that performs work, and can use skills as part of that work.
• Instructions or custom agents: an AGENTS.md file gives guidance to an existing agent. Despite its name, it doesn't define a custom agent.

For supported services, Copilot connectors provide managed MCP connections without local server setup or configuration files. Use a manually configured MCP server when you need another integration or its configuration options.

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.

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.

• Customizations are the instructions, workflows, tools, and other building blocks an agent uses.
• Plugins package related customizations for installation together. A plugin can include skills, custom agents, hooks, and MCP servers.
• Plugin marketplaces are catalogs of plugins. Adding a marketplace makes its plugins available to browse. Installing a plugin makes its supported components available to your harness.

The Customization Marketplace 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.

Model-driven vs. deterministic behavior

Most customizations guide the model or give it more options. The model interprets instructions, decides whether a skill is relevant, and chooses when to call an available tool. The result depends on the request, available context, and model reasoning.

The runtime triggers a hook when its configured event occurs, such as a tool call starting or finishing. Use a hook for actions such as validating a tool call or starting a formatter after an edit. Discovery, trust, filters, timeouts, and error handling still affect execution. Use instructions when you want to guide how the agent reasons or writes code.

For example, an instruction that says "run the formatter after editing a file" asks the model to remember and perform that action. A hook configured to run after the editing tool completes performs that action regardless of whether the model remembers the instruction.

How customizations combine

Customization types are building blocks rather than mutually exclusive alternatives. The following pull request workflow illustrates how they can work together, not a minimum setup to create. Add only the parts your workflow needs:

1. Instructions provide the repository's coding standards and pull request conventions.
2. A custom agent gives the agent a focused role and limits it to the tools needed for the task.
3. An agent skill supplies the steps, scripts, and templates for preparing the pull request.
4. An MCP server provides tools to retrieve the related issue from an external issue tracker.
5. Hooks run configured validation after the agent edits files or reject disallowed tool calls before they run.

Each layer has a separate responsibility. You can update the coding standards without changing the workflow, or replace the external system without rewriting the agent's role.

A plugin can distribute the complete configuration, for example within your organization, so that other developers can install the same skills and MCP servers.

Customization scope

Scope determines where a customization is available and who can share it. It is separate from activation: a workspace customization isn't necessarily included in every request. Depending on the customization type, you can define it at one or more of these levels:

• User: available to you across workspaces.
• Workspace or repository: stored with the project and shared with contributors through source control.
• Organization: managed centrally and shared across repositories, where supported.

Choose the narrowest scope that matches the information. Personal preferences belong at the user level. Project architecture and repository-specific workflows belong in the repository. Organization-wide requirements belong at the organization level when the customization type supports it.

Agent memory is separate from project customization. Use local memory for personal preferences or emerging observations that aren't ready to share. Put reviewed project rules and workflows that contributors depend on in repository documentation or customizations so your team can review and maintain them.

Not every customization type supports every scope or agent harness. Before creating files, check compatibility and choose a scope. Enterprise policies can further restrict the customizations available to you.

Related resources

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