Copilot CLI: Document the built-in agents (#60467)

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: hubwriter

content/copilot/concepts/agents/coding-agent/about-custom-agents.md

@@ -9,54 +9,9 @@ category:
 contentType: concepts
 ---
 
-## About {% data variables.copilot.custom_agents_short %}
+{% data reusables.copilot.copilot-cli.custom-agents-about-intro %}
 
-{% data variables.copilot.custom_agents_caps_short %} are specialized versions of the {% data variables.product.prodname_copilot_short %} agent that you can tailor to your unique workflows, coding conventions, and use cases. They act like tailored teammates that follow your standards, use the right tools, and implement team-specific practices. You define these agents once instead of repeatedly providing the same instructions and context.
-
-You define {% data variables.copilot.custom_agents_short %} using Markdown files called {% data variables.copilot.agent_profiles %}. These files specify prompts, tools, and MCP servers. This allows you to encode your conventions, frameworks, and desired outcomes directly into {% data variables.product.prodname_copilot_short %}.
-
-The {% data variables.copilot.agent_profile %} defines the {% data variables.copilot.copilot_custom_agent_short %}'s behavior. When you assign the agent to a task or issue, it instantiates the {% data variables.copilot.copilot_custom_agent_short %}.
-
-## {% data variables.copilot.agent_profile_caps %} format
-
-{% data variables.copilot.agent_profiles_caps %} are Markdown files with YAML frontmatter. In their simplest form, they include:
-
-* **Name**: A unique identifier for the {% data variables.copilot.copilot_custom_agent_short %}.
-* **Description**: Explains the agent's purpose and capabilities.
-* **Prompt**: Custom instructions that define the agent's behavior and expertise.
-* **Tools** (optional): Specific tools the agent can access. By default, agents can access all available tools, including built-in tools and MCP server tools.
-
-{% data variables.copilot.agent_profiles_caps %} can also include MCP server configurations using the `mcp-server` property.
-
-### Example {% data variables.copilot.agent_profile %}
-
-This example is a basic {% data variables.copilot.agent_profile %} with name, description, and prompt configured.
-
-```text
----
-name: readme-creator
-description: Agent specializing in creating and improving README files
----
-
-You are a documentation specialist focused on README files. Your scope is limited to README  files or other related documentation files only - do not modify or analyze code files.
-
-Focus on the following instructions:
-- Create and update README.md files with clear project descriptions
-- Structure README sections logically: overview, installation, usage, contributing
-- Write scannable content with proper headings and formatting
-- Add appropriate badges, links, and navigation elements
-- Use relative links (e.g., `docs/CONTRIBUTING.md`) instead of absolute URLs for files within the repository
-- Make links descriptive and add alt text to images
-```
-
-## Where you can configure {% data variables.copilot.custom_agents_short %}
-
-You can define {% data variables.copilot.agent_profiles %} at different levels:
-
-* **Repository level**: Create `.github/agents/CUSTOM-AGENT-NAME.md` in your repository for project-specific agents.
-* **Organization or enterprise level**: Create `/agents/CUSTOM-AGENT-NAME.md` in a `.github-private` repository for broader availability.
-
-For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents).
+{% data reusables.copilot.copilot-cli.custom-agents-about-details %}
 
 ## Where you can use {% data variables.copilot.custom_agents_short %}
 

content/copilot/concepts/agents/copilot-cli/about-custom-agents.md

@@ -0,0 +1,47 @@
+---
+title: About custom agents
+shortTitle: Custom agents
+intro: '{% data variables.copilot.custom_agents_caps_short %} enhance {% data variables.product.prodname_copilot_short %} with assistance tailored to your needs.'
+versions:
+  feature: copilot
+category:
+  - Learn about Copilot
+contentType: concepts
+---
+
+{% data reusables.copilot.copilot-cli.custom-agents-about-intro %}
+
+In addition to any {% data variables.copilot.custom_agents_short %} you define yourself, {% data variables.product.prodname_copilot_short %} includes a set of pre-built {% data variables.copilot.custom_agents_short %}. See [Built-in agents](#built-in-agents).
+
+{% data reusables.copilot.copilot-cli.custom-agents-about-details %}
+
+## Built-in agents
+
+In addition to the main {% data variables.product.prodname_copilot_short %} agent, which processes your request when you submit a prompt, {% data variables.copilot.copilot_cli_short %} includes the following built-in agents which the main agent can run as subagents to assist with common development tasks. These agents are optimized for efficiency and accuracy, leveraging the capabilities of the underlying language models and tools to provide high-quality assistance in their respective domains.
+
+{% data variables.product.prodname_copilot_short %} will automatically use an appropriate built-in agent based on your prompt and the current context. For example, the prompt `How does authentication work in this codebase?` will typically trigger the Explore agent, and using the `/research` slash command will trigger the Research agent.
+
+* **explore** — A fast, lightweight codebase exploration agent. It uses code intelligence, grep, glob, view, and shell tools to search files and understand code structure. It will not change any files, so can be called in parallel to other subagents being run by the main {% data variables.product.prodname_copilot_short %} agent. It has read-only access to GitHub MCP server tools.
+
+* **task** — A command execution agent that runs development commands (tests, builds, linters, formatters, dependency installs) and reports results efficiently. It returns a brief summary on success, and full output on failure, keeping the main context clean. It has access to all of the tools the parent agent can use (excluding some that are not appropriate in a subagent context), with the same permissions granted or denied.
+
+* **general-purpose** — This agent essentially has all of the same capabilities as the main {% data variables.product.prodname_copilot_short %} agent. The main agent can run the general-purpose agent as a subagent to assist with any task that requires a separate context window, or to run in parallel when appropriate.
+
+* **code-review** — Reviews code changes with an extremely high signal-to-noise ratio. This agent analyzes staged/unstaged changes and branch diffs, surfacing only issues that genuinely matter: bugs, security vulnerabilities, race conditions, memory leaks, and logic errors. It never comments on style or formatting. It will not make any changes to files.
+
+* **research** — This agent operates as a staff-level software engineer and research specialist. It provides exhaustive, meticulously researched answers about codebases, APIs, libraries, and software architecture. It uses {% data variables.product.github %} search/exploration tools, web fetch/search, and local tools. Unlike the other agents, the research agent can only be invoked by using the `/research` slash command. It cannot be automatically triggered by the main agent.
+
+## Running agents as subagents
+
+One of the benefits of using custom agents you have defined yourself—or the built-in agents—is that the main {% data variables.product.prodname_copilot_short %} agent can run them as subagents with a separate context window. This means that your custom agent, or built-in agent, can focus on a specific subtask without cluttering the context window of the main agent.
+
+Where appropriate, tasks performed by subagents can be run in parallel, allowing the overall task to be completed more quickly.
+
+For more information, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/comparing-cli-features).
+
+## Next steps
+
+To create your own {% data variables.copilot.custom_agents_short %}, see:
+
+* [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli)
+* [AUTOTITLE](/copilot/reference/customization-cheat-sheet)

content/copilot/concepts/agents/copilot-cli/index.md

@@ -7,6 +7,7 @@ versions:
   feature: copilot
 children:
   - /about-copilot-cli
+  - /about-custom-agents
   - /about-cli-plugins
   - /comparing-cli-features
   - /autopilot

content/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli.md

@@ -20,7 +20,7 @@ When you prompt {% data variables.product.prodname_copilot_short %} to carry out
 
 Work performed by a {% data variables.copilot.copilot_custom_agent_short %} is carried out using a subagent, which is a temporary agent spun up to complete the task. The subagent has its own context window, which can be populated by information that is not relevant to the main agent. In this way, especially for larger tasks, parts of the work can be offloaded to {% data variables.copilot.custom_agents_short %}, without cluttering the main agent's context window. The main agent can then focus on higher-level planning and coordination.
 
-For more information, see [AUTOTITLE](/copilot/concepts/agents/coding-agent/about-custom-agents).
+For more information, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/about-custom-agents).
 
 ## Creating a {% data variables.copilot.copilot_custom_agent_short %}
 

data/reusables/copilot/copilot-cli/custom-agents-about-details.md

@@ -0,0 +1,40 @@
+## {% data variables.copilot.agent_profile_caps %} format
+
+{% data variables.copilot.agent_profiles_caps %} are Markdown files with YAML frontmatter. In their simplest form, they include:
+
+* **Name** (optional): A display name for the {% data variables.copilot.copilot_custom_agent_short %}. If omitted, the agent's filename is used as its identifier and default display name.
+* **Description**: Explains the agent's purpose and capabilities.
+* **Prompt**: Custom instructions that define the agent's behavior and expertise.
+* **Tools** (optional): Specific tools the agent can access. By default, agents can access all available tools, including built-in tools, and MCP server tools.
+
+{% data variables.copilot.agent_profiles_caps %} can also include MCP server configurations using the `mcp-servers` property.
+
+### Example {% data variables.copilot.agent_profile %}
+
+This example is a basic {% data variables.copilot.agent_profile %} with name, description, and prompt configured.
+
+```text
+---
+name: readme-creator
+description: Agent specializing in creating and improving README files
+---
+
+You are a documentation specialist focused on README files. Your scope is limited to README files or other related documentation files only - do not modify or analyze code files.
+
+Focus on the following instructions:
+- Create and update README.md files with clear project descriptions
+- Structure README sections logically: overview, installation, usage, contributing
+- Write scannable content with proper headings and formatting
+- Add appropriate badges, links, and navigation elements
+- Use relative links (e.g., `docs/CONTRIBUTING.md`) instead of absolute URLs for files within the repository
+- Make links descriptive and add alt text to images
+```
+
+## Where you can configure {% data variables.copilot.custom_agents_short %}
+
+You can define {% data variables.copilot.agent_profiles %} at different levels:
+
+* **Repository level**: Create `.github/agents/CUSTOM-AGENT-NAME.md` in your repository for project-specific agents.
+* **Organization or enterprise level**: Create `/agents/CUSTOM-AGENT-NAME.md` in a `.github-private` repository for broader availability.
+
+For more information, see [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-organization/prepare-for-custom-agents) and [AUTOTITLE](/copilot/how-tos/administer-copilot/manage-for-enterprise/manage-agents/prepare-for-custom-agents).

data/reusables/copilot/copilot-cli/custom-agents-about-intro.md

@@ -0,0 +1,7 @@
+## About {% data variables.copilot.custom_agents_short %}
+
+{% data variables.copilot.custom_agents_caps_short %} are specialized versions of the {% data variables.product.prodname_copilot_short %} agent that you can tailor to your unique workflows, coding conventions, and use cases. They act like tailored teammates that follow your standards, use the right tools, and implement team-specific practices. You define these agents once instead of repeatedly providing the same instructions and context.
+
+You define {% data variables.copilot.custom_agents_short %} using Markdown files called {% data variables.copilot.agent_profiles %}. These files specify prompts, tools, and MCP servers. This allows you to encode your conventions, frameworks, and desired outcomes directly into {% data variables.product.prodname_copilot_short %}.
+
+The {% data variables.copilot.agent_profile %} defines the {% data variables.copilot.copilot_custom_agent_short %}'s behavior. When you assign the agent to a task or issue, it instantiates the {% data variables.copilot.copilot_custom_agent_short %}.