invoke-custom-agents.md

title	Invoking custom agents
shortTitle	Invoke custom agents
intro	Use custom agents, skills, and MCP servers in {% data variables.copilot.copilot_cli_short %} to extend its capabilities.
product	{% data reusables.gated-features.copilot-cli %}
versions	feature copilot
contentType	how-tos
redirect_from	/copilot/how-tos/copilot-cli/use-copilot-cli-agents/invoke-custom-agents
category	Build with Copilot CLI
docsTeamMetrics	copilot-cli

Use {% data variables.copilot.custom_agents_short %}

A {% data variables.copilot.copilot_custom_agent_short %} is a specialized version of {% data variables.product.prodname_copilot_short %}. {% data variables.copilot.custom_agents_caps_short %} help {% data variables.product.prodname_copilot_short %} handle unique workflows, particular coding conventions, and specialist use cases.

{% data variables.copilot.copilot_cli_short %} includes a default group of {% data variables.copilot.custom_agents_short %} for common tasks:

Agent	Description
Explore	Performs quick codebase analysis, allowing you to ask questions about your code without adding to your main context.
Task	Executes commands such as tests and builds, providing brief summaries on success and full output on failure.
General-purpose	Handles complex, multi-step tasks that require the full toolset and high-quality reasoning, running in a separate context to keep your main conversation clearly focused.
Code-review	Reviews changes with a focus on surfacing only genuine issues, minimizing noise.

The AI model being used by the CLI can choose to delegate a task to a subsidiary subagent process, that operates using a {% data variables.copilot.copilot_custom_agent_short %} with specific expertise, if it judges that this would result in the work being completed more effectively. The model may equally choose to handle the work directly in the main agent.

You can define your own {% data variables.copilot.custom_agents_short %} using Markdown files, called {% data variables.copilot.agent_profiles %}, that specify what expertise the agent should have, what tools it can use, and any specific instructions for how it should respond.

You can define {% data variables.copilot.custom_agents_short %} at the user, repository, organization, or enterprise level:

Type	Location	Scope
User-level {% data variables.copilot.copilot_custom_agent_short %}	local ~/.copilot/agents directory	All projects
Repository-level {% data variables.copilot.copilot_custom_agent_short %}	.github/agents directory in your local and remote repositories	Current project
Organization-level {% data variables.copilot.copilot_custom_agent_short %}	/agents directory in the organization's .github or .github-private repository	All projects within the organization
Enterprise-level {% data variables.copilot.copilot_custom_agent_short %}	/agents directory in the .github-private repository of an organization designated in enterprise settings. For more information, see AUTOTITLE.	All projects under the enterprise account

In the case of naming conflicts (where agents share the same filename), a user-level agent overrides a repository-level agent, a repository-level agent overrides an organization-level agent, and an organization-level agent overrides an enterprise-level agent.

{% data variables.copilot.custom_agents_caps_short %} can be used in three ways:

• Using the slash command in the CLI's interactive interface to select from the list of available {% data variables.copilot.custom_agents_short %}:

  /agent

• Calling out to the {% data variables.copilot.copilot_custom_agent_short %} directly in a prompt:

  Use the refactoring agent to refactor this code block

  {% data variables.product.prodname_copilot_short %} will automatically infer the agent you want to use.

• Specifying the {% data variables.copilot.copilot_custom_agent_short %} you want to use with the command-line option. For example:

  copilot --agent=refactor-agent --prompt "Refactor this code block"

For more information, see AUTOTITLE.

Use skills

You can create skills to enhance the ability of {% data variables.product.prodname_copilot_short %} to perform specialized tasks with instructions, scripts, and resources.

For more information, see AUTOTITLE.

Add an MCP server

{% data variables.copilot.copilot_cli_short %} comes with the {% data variables.product.github %} MCP server already configured. This MCP server allows you to interact with resources on {% data variables.product.prodname_dotcom_the_website %}—for example, allowing you to merge pull requests from the CLI.

To extend the functionality available to you in {% data variables.copilot.copilot_cli_short %}, you can add more MCP servers:

1. Use the following slash command:

   /mcp add

2. Fill in the details for the MCP server you want to add, using the Tab key to move between fields.

3. Press Ctrl+S to save the details.

Details of your configured MCP servers are stored in the mcp-config.json file, which is located, by default, in the ~/.copilot directory. This location can be changed by setting the COPILOT_HOME environment variable. For information about the JSON structure of a server definition, see AUTOTITLE.

For more detailed information on adding and managing MCP servers in {% data variables.copilot.copilot_cli_short %}, see AUTOTITLE.

Next steps

To learn how to guide and refine agent behavior during task execution to keep work on track, see AUTOTITLE.