diff --git a/CHANGELOG.md b/CHANGELOG.md index e73e53f2dd1b..835a5539e5a0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,13 @@ # Docs changelog +**3 March 2026** + +We've added a new reference article, [Copilot customization cheat sheet](https://docs.github.com/copilot/reference/customization-cheat-sheet), to help you choose the right Copilot customization approach for your workflow. + +The article compares Copilot customization options, including what each one does, how to configure it, and where it is supported across IDEs and Copilot surfaces. It also explains what each option is best for, with common use cases to help you decide what to use. + +
+ **2 March 2026** We've added an article about the new `/research` slash command in Copilot CLI: diff --git a/content/copilot/how-tos/copilot-cli/index.md b/content/copilot/how-tos/copilot-cli/index.md index 24c3080928ee..27c388e84887 100644 --- a/content/copilot/how-tos/copilot-cli/index.md +++ b/content/copilot/how-tos/copilot-cli/index.md @@ -1,7 +1,7 @@ --- title: '{% data variables.copilot.copilot_cli %}' shortTitle: '{% data variables.copilot.copilot_cli_short %}' -intro: 'Use {% data variables.product.prodname_copilot_short %} directly from your terminal to answer questions, write and debug code, and interact with {% data variables.product.github %}.' +intro: Use {% data variables.product.prodname_copilot_short %} directly from your terminal to answer questions, write and debug code, and interact with {% data variables.product.github %}. versions: feature: copilot contentType: landing @@ -21,7 +21,7 @@ children: - /cli-best-practices - /set-up-copilot-cli - /customize-copilot - - /use-copilot-cli + - /use-copilot-cli-agents - /administer-copilot-cli-for-your-enterprise - /automate-with-actions - /speeding-up-task-completion @@ -50,7 +50,7 @@ children: - /content/copilot/responsible-use/copilot-cli carousels: recommended: - - /copilot/how-tos/copilot-cli/use-copilot-cli + - /copilot/how-tos/copilot-cli/use-copilot-cli-agents/overview - /copilot/how-tos/copilot-cli/cli-best-practices - /copilot/reference/cli-command-reference includedCategories: @@ -60,3 +60,4 @@ includedCategories: - Build with Copilot CLI - Administer Copilot CLI --- + diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review.md new file mode 100644 index 000000000000..7a92f4260d65 --- /dev/null +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review.md @@ -0,0 +1,29 @@ +--- +title: Requesting a code review with {% data variables.copilot.copilot_cli %} +shortTitle: Agentic code review +allowTitleToDifferFromFilename: true +intro: 'Use {% data variables.copilot.copilot_cli_short %} to review your code changes directly from the terminal.' +product: '{% data reusables.gated-features.copilot-cli %}' +versions: + feature: copilot +topics: + - Copilot +contentType: how-tos +category: + - Build with Copilot CLI +--- + +## About agentic code review + +You can use the `/review` slash command to have {% data variables.product.prodname_copilot_short %} analyze code changes without leaving the CLI. This lets you get quick feedback on your changes prior to committing. + +1. Type `/review` and optionally specify a prompt, path, or file pattern to narrow the review scope, then press Enter. +1. If {% data variables.product.prodname_copilot_short %} proposes running a command (for example, to inspect a diff or verify a file), review the command, then use the arrow keys to choose an option and press Enter. + * Select **Yes** to run the command. + * Select **No** to skip the command and tell {% data variables.product.prodname_copilot_short %} what to do differently. +1. Read the feedback that {% data variables.product.prodname_copilot_short %} provides about your changes and apply any suggested improvements in your code editor. + +## Further reading + +* [AUTOTITLE](/copilot/how-tos/copilot-cli/automate-with-actions) +* [AUTOTITLE](/copilot/how-tos/copilot-cli/add-custom-instructions) diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/delegate-tasks-to-cca.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/delegate-tasks-to-cca.md new file mode 100644 index 000000000000..0ec73068654d --- /dev/null +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/delegate-tasks-to-cca.md @@ -0,0 +1,49 @@ +--- +title: Delegating tasks to {% data variables.copilot.copilot_cli %} +shortTitle: Delegate tasks to Copilot +intro: Use {% data variables.copilot.copilot_cli_short %}''s autopilot mode to hand off tasks and have {% data variables.product.prodname_copilot_short %} work autonomously on your behalf. +allowTitleToDifferFromFilename: true +product: '{% data reusables.gated-features.copilot-cli %}' +versions: + feature: copilot +topics: + - Copilot +contentType: how-tos +category: + - Build with Copilot CLI +--- + +## Get {% data variables.product.prodname_copilot_short %} to work autonomously + +You can tell {% data variables.product.prodname_copilot_short %} to use its best judgment to complete a task autonomously, rather than the CLI prompting you for input at each decision point within a task. You do this by using the CLI's autopilot mode. + +There are two ways to use autopilot mode: + +* **Interactively:** In an interactive session, press Shift+Tab until you see "autopilot" in the status bar. If prompted to choose permissions for autopilot mode, allow full permissions, then enter your prompt. +* **Programmatically:** Pass the CLI a prompt directly in a command, and include the `--autopilot` option. For example, to use autopilot mode with full permissions, restricting it to 10 continuations, enter `{% data reusables.cli.autopilot-programmatic-prompt %}`. + +For more information, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/autopilot). + +## Delegate tasks to {% data variables.copilot.copilot_coding_agent %} + +The delegate command lets you push your current session to {% data variables.copilot.copilot_coding_agent %} on {% data variables.product.github %}. This lets you hand off work while preserving all the context {% data variables.product.prodname_copilot_short %} needs to complete your task. + +You can delegate a task using the slash command, followed by a prompt: + +```shell +/delegate complete the API integration tests and fix any failing edge cases +``` + +Alternatively, prefix a prompt with `&` to delegate it: + +```shell +& complete the API integration tests and fix any failing edge cases +``` + +{% data variables.product.prodname_copilot_short %} will ask to commit any of your unstaged changes as a checkpoint in a new branch it creates. {% data variables.copilot.copilot_coding_agent %} will open a draft pull request, make changes in the background, and request a review from you. + +{% data variables.product.prodname_copilot_short %} will provide a link to the pull request and agent session on {% data variables.product.github %} once the session begins. + +## Next steps + +To learn how to invoke specialized agents tailored to specific tasks, such as code review, documentation, or security audits, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/invoke-custom-agents). diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/index.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/index.md new file mode 100644 index 000000000000..ced9e83a5c9f --- /dev/null +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/index.md @@ -0,0 +1,17 @@ +--- +title: Use {% data variables.copilot.copilot_cli %} agents +shortTitle: Use Copilot CLI agents +intro: Understand the different ways you can use agents in {% data variables.copilot.copilot_cli_short %} to delegate and automate work. +versions: + feature: copilot +topics: + - Copilot +children: + - /overview + - /delegate-tasks-to-cca + - /invoke-custom-agents + - /steer-agents + - /agentic-code-review +contentType: how-tos +--- + diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/invoke-custom-agents.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/invoke-custom-agents.md new file mode 100644 index 000000000000..f22da83034e2 --- /dev/null +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/invoke-custom-agents.md @@ -0,0 +1,113 @@ +--- +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 +topics: + - Copilot +contentType: how-tos +category: + - Build with 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: + + + + + + + + + + + + + + + + + + + + + + + + + + +
AgentDescription
ExplorePerforms quick codebase analysis, allowing you to ask questions about your code without adding to your main context.
TaskExecutes commands such as tests and builds, providing brief summaries on success and full output on failure.
General-purposeHandles 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-reviewReviews 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, or organization/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 and Enterprise-level {% data variables.copilot.copilot_custom_agent_short %} | `/agents` directory in the `.github-private` repository in an organization or enterprise | All projects under your organization and enterprise account | + +In the case of naming conflicts, a system-level agent overrides a repository-level agent, and the repository-level agent would override an organization-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 %}: + + ```shell + /agent + ``` + +* Calling out to the {% data variables.copilot.copilot_custom_agent_short %} directly in a prompt: + + ```shell + 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: + + ```shell + copilot --agent=refactor-agent --prompt "Refactor this code block" + ``` + +For more information, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/create-custom-agents). + +## 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](/copilot/how-tos/copilot-cli/customize-copilot/create-skills). + +## 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: + + ```shell + /mcp add + ``` + +1. Fill in the details for the MCP server you want to add, using the Tab key to move between fields. +1. 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 `XDG_CONFIG_HOME` environment variable. For information about the JSON structure of a server definition, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp#writing-a-json-configuration-for-mcp-servers). + +For more detailed information on adding and managing MCP servers in {% data variables.copilot.copilot_cli_short %}, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers). + +## Next steps + +To learn how to guide and refine agent behavior during task execution to keep work on track, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/steer-agents). diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/overview.md similarity index 83% rename from content/copilot/how-tos/copilot-cli/use-copilot-cli.md rename to content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/overview.md index dc0b9ea284ab..f747ed33c890 100644 --- a/content/copilot/how-tos/copilot-cli/use-copilot-cli.md +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/overview.md @@ -1,17 +1,18 @@ --- title: Using GitHub Copilot CLI -shortTitle: Use Copilot CLI +shortTitle: Overview intro: Learn how to use {% data variables.product.prodname_copilot %} from the command line. product: '{% data reusables.gated-features.copilot-cli %}' redirect_from: - /copilot/how-tos/use-copilot-cli - /copilot/how-tos/use-copilot-agents/use-copilot-cli + - /copilot/how-tos/copilot-cli/use-copilot-cli versions: feature: copilot contentType: how-tos category: - - Author and optimize with Copilot # Copilot discovery page - - Build with Copilot CLI # Copilot CLI bespoke page + - Author and optimize with Copilot + - Build with Copilot CLI --- The command-line interface (CLI) for {% data variables.product.prodname_copilot %} allows you to use {% data variables.product.prodname_copilot_short %} directly from your terminal. For more information, see [AUTOTITLE](/copilot/concepts/agents/about-copilot-cli). @@ -85,10 +86,6 @@ If you enter a prompt and then decide you want to stop {% data variables.product Plan mode lets you collaborate with {% data variables.product.prodname_copilot_short %} on an implementation plan before any code is written. Press Shift+Tab to cycle in and out of plan mode. -### Steer the conversation while {% data variables.product.prodname_copilot_short %} is thinking - -You can interact with {% data variables.product.prodname_copilot_short %} while it's thinking. Send follow-up messages to steer the conversation in a different direction, or queue additional instructions for {% data variables.product.prodname_copilot_short %} to process after it finishes its current response. - ### Include a specific file in your prompt To add a specific file to your prompt, use `@` followed by the relative path to the file. For example: `Explain @config/ci/ci-required-checks.yml` or `Fix the bug in @src/app.js`. This adds the contents of the file to your prompt as context for {% data variables.product.prodname_copilot_short %}. @@ -119,37 +116,6 @@ You can prepend your input with `!` to directly run shell commands, without maki !git clone https://github.com/github/copilot-cli ``` -### Get {% data variables.product.prodname_copilot_short %} to work autonomously - -You can tell {% data variables.product.prodname_copilot_short %} to use its best judgment to complete a task autonomously, rather than the CLI prompting you for input at each decision point within a task. You do this by using the CLI's autopilot mode. - -There are two ways to use autopilot mode: - -* **Interactively:** In an interactive session, press Shift+Tab until you see "autopilot" in the status bar. If prompted to choose permissions for autopilot mode, allow full permissions, then enter your prompt. -* **Programmatically:** Pass the CLI a prompt directly in a command, and include the `--autopilot` option. For example, to use autopilot mode with full permissions, restricting it to 10 continuations, enter `{% data reusables.cli.autopilot-programmatic-prompt %}`. - -For more information, see [AUTOTITLE](/copilot/concepts/agents/copilot-cli/autopilot). - -### Delegate tasks to {% data variables.copilot.copilot_coding_agent %} - -The delegate command lets you push your current session to {% data variables.copilot.copilot_coding_agent %} on {% data variables.product.github %}. This lets you hand off work while preserving all the context {% data variables.product.prodname_copilot_short %} needs to complete your task. - -You can delegate a task using the slash command, followed by a prompt: - -```shell -/delegate complete the API integration tests and fix any failing edge cases -``` - -Alternatively, prefix a prompt with `&` to delegate it: - -```shell -& complete the API integration tests and fix any failing edge cases -``` - -{% data variables.product.prodname_copilot_short %} will ask to commit any of your unstaged changes as a checkpoint in a new branch it creates. {% data variables.copilot.copilot_coding_agent %} will open a draft pull request, make changes in the background, and request a review from you. - -{% data variables.product.prodname_copilot_short %} will provide a link to the pull request and agent session on {% data variables.product.github %} once the session begins. - ### Resume an interactive session You can use the `--resume` command-line option or the `/resume` slash command to select and resume an interactive CLI session, allowing you to pick up right where you left off, with the saved context. You can kick off a {% data variables.copilot.copilot_coding_agent %} session on {% data variables.product.github %}, and then use {% data variables.copilot.copilot_cli %} to bring that session to your local environment. @@ -267,8 +233,6 @@ To extend the functionality available to you in {% data variables.copilot.copilo 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 `XDG_CONFIG_HOME` environment variable. For information about the JSON structure of a server definition, see [AUTOTITLE](/copilot/how-tos/use-copilot-agents/coding-agent/extend-coding-agent-with-mcp#writing-a-json-configuration-for-mcp-servers). -For more detailed information on adding and managing MCP servers in {% data variables.copilot.copilot_cli_short %}, see [AUTOTITLE](/copilot/how-tos/copilot-cli/customize-copilot/add-mcp-servers). - ### Context management {% data variables.copilot.copilot_cli_short %} provides several slash commands to help you monitor and manage your context window: @@ -284,10 +248,6 @@ For more detailed information on adding and managing MCP servers in {% data vari {% data variables.copilot.copilot_cli %} automatically compresses your history in the background when your conversation approaches 95% of the token limit, without interrupting your workflow. -### Review code changes - -You can use the `/review` slash command to have {% data variables.product.prodname_copilot_short %} analyze code changes without leaving the CLI. This lets you get quick feedback on your changes prior to committing. - ### Enable all permissions For situations where you trust {% data variables.product.prodname_copilot_short %} to run freely, you can use the `--allow-all` or `--yolo` flags to enable all permissions at once. @@ -325,6 +285,17 @@ For additional information use one of the following commands in your terminal: {% data reusables.cli.feedback %} +## Next steps + +{% data variables.copilot.copilot_cli_short %} can operate as a conversational assistant, answering questions and helping you write code interactively. Beyond chat, {% data variables.copilot.copilot_cli_short %} supports a range of agentic modes that allow you to delegate tasks with greater autonomy. + +You can work with agents in {% data variables.copilot.copilot_cli_short %} to support a full task lifecycle, from delegating work to reviewing results: + +* **Delegate tasks autonomously**: Run {% data variables.copilot.copilot_cli_short %} in autopilot mode to complete multi-step tasks without requiring approval at each step. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/delegate-tasks-to-cca). +* **Invoke custom agents**: Invoke specialized agents tailored to specific tasks, such as code review, documentation, or security audits. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/invoke-custom-agents). +* **Steer agents**: Guide and refine agent behavior during task execution to keep work on track. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/steer-agents). +* **Request a code review**: Use {% data variables.copilot.copilot_cli_short %} to get an AI-powered review of your code changes. See [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review). + ## Further reading * [AUTOTITLE](/copilot/how-tos/copilot-cli/cli-best-practices) diff --git a/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/steer-agents.md b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/steer-agents.md new file mode 100644 index 000000000000..6079908b48c6 --- /dev/null +++ b/content/copilot/how-tos/copilot-cli/use-copilot-cli-agents/steer-agents.md @@ -0,0 +1,27 @@ +--- +title: Steering agents in {% data variables.copilot.copilot_cli %} +shortTitle: Steer agents +intro: Guide {% data variables.product.prodname_copilot_short %} during task execution to keep work on track with your intent. +product: '{% data reusables.gated-features.copilot-cli %}' +versions: + feature: copilot +topics: + - Copilot +contentType: how-tos +category: + - Build with Copilot CLI +--- + +## Steer the conversation while {% data variables.product.prodname_copilot_short %} is thinking + +You can interact with {% data variables.product.prodname_copilot_short %} while it's thinking. Send follow-up messages to steer the conversation in a different direction, or queue additional instructions for {% data variables.product.prodname_copilot_short %} to process after it finishes its current response. + +Steering lets you: + +* Interrupt an agent that is heading in the wrong direction. +* Provide inline feedback when rejecting a tool permission request. +* Refine or clarify the task scope partway through execution. + +## Next steps + +To learn how to use {% data variables.copilot.copilot_cli_short %} to get an AI-powered review of your code changes, see [AUTOTITLE](/copilot/how-tos/copilot-cli/use-copilot-cli-agents/agentic-code-review).