Creating and using custom agents for GitHub Copilot CLI

Create specialized agents with tailored expertise for specific development tasks.

In this article

Introduction

Custom agents allow you to tailor Copilot's expertise for specific tasks.

When you prompt Copilot to carry out a task it may choose to use one of your custom agents, if Copilot determines that the agent's expertise is a good fit for the task.

Work performed by a custom agent 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 custom agents, without cluttering the main agent's context window. The main agent can then focus on higher-level planning and coordination.

For more information, see About custom agents.

Creating a custom agent

Each custom agent is defined by a Markdown file with an .agent.md extension. You can create these files yourself, or you can add them from within the CLI, as described in the following steps.

  1. In interactive mode, enter /agent.

  2. Select Create new agent from the list of options.

  3. Choose between the options to create the custom agent in the repository or in your home directory:

    • Project (.github/agents/)

    • User (~/.copilot/agents/)

    Note

    If personal and repository custom agents have the same ID, the personal agent is used. For an agent at the root of an agents directory, the ID is the file name without the .agent.md or .md extension. The optional name field does not affect deduplication. Agents with the same name but different IDs both load, but if an --agent value matches more than one ID or name, the CLI uses the highest-priority match.

  4. Choose whether to get Copilot to create the custom agent file, or create it yourself.

    Option 1: Use Copilot

    Enter details of the agent you want to create. Describe the agent's expertise and when the agent should be used. Copilot will take the description you enter and use it to write an agent profile for you.

    For example, you could enter:

    I am a security expert. I check code files thoroughly for potential security issues. Use me whenever a security review/check/audit is requested for one or more code files, or when the word "seccheck" is used in a prompt in reference to code files.

I will identify potential problems, such as code that:

- Exposes secrets or credentials
- Allows cross-site scripting
- Allows SQL injection
- Contains vulnerable dependencies
- Allows authentication to be bypassed

If any problems are identified, create a single GitHub issue in this repository on GitHub.com with details of problems, giving full details of each issue, including, but not limited to, risk level and recommended fix.

    After Copilot finishes generating the initial agent profile it displays the following options:

    • Continue
    • Review content
    • Try again
    • Quit

    If you choose to review the content, the agent file is opened in your default editor. You can review and make changes, if required, before continuing the agent creation process in the CLI.

    To complete the creation process, choose Continue.

    Option 2: Create the agent profile manually

    When you choose to create the agent file yourself, you'll be guided through a series of prompts to fill in the necessary information to create the agent profile.

    1. Enter a name for the agent. The name you enter is the name that's displayed when you list the available agents. A version of this will be used as the name of the agent file—for example, if you enter "Security expert", the agent file will be named security-expert.agent.md.

      Tip

      For ease of use when using a custom agent programmatically, it's recommended that you choose a name consisting only of lowercase letters and hyphens.

    2. Enter a description that states what expertise this agent has and when it should be used.

    3. Enter instructions for how the agent should behave, including any specific guidelines, actions it should take or constraints it should follow.

  5. Choose which tools your custom agent should have access to.

    By default, custom agents have access to all tools. If you restrict an agent's access, a tools specification is added to the agent file.

  6. Restart the CLI to load your new custom agent.

Using a custom agent

Custom agents can be used in the following ways:

  • Slash command

    Enter /agent in interactive mode and choose from the list of available custom agents. Then enter a prompt that will be passed to the selected agent.

    Note

    The CLI's default agents are not included in this list. For more information about the default agents, see About custom agents.

  • Explicit instruction

    Tell Copilot to use a specific agent. For example:

    Use the security-auditor agent on all files in the /src/app directory

  • By inference

    Use a prompt that will trigger the use of a particular agent based on the description in the agent file. For example:

    Check all TypeScript files in or under the src directory for potential security problems

    or (where "seccheck" is defined as a trigger word in the agent profile):

    seccheck /src/app/validator.go

    Copilot will automatically infer the agent you want to use.

  • Programmatically

    Specify the custom agent you want to use with the command-line option. For example:

    copilot --agent security-auditor --prompt "Check /src/app/validator.go"

    In this example, security-auditor is the ID of the custom agent. The ID is derived from the file name, without the .md or .agent.md extension. In this case, the path to the file is either agents/security-auditor.md or agents/security-auditor.agent.md. If the file is in a subdirectory of agents, the subdirectory name is included in the ID, with the directory separator replaced with --. So an agent file at agents/security/security-auditor.agent.md would have the ID security--security-auditor. Alternatively, you can use the value of the name field instead of the ID, enclosing it in quotes. For example, --agent "Security Auditor".

Applying your repository's custom instructions to a custom agent

Custom instruction files—such as .github/copilot-instructions.md, AGENTS.md, and CLAUDE.md—tell Copilot how to work in your repository. For more information, see Adding repository custom instructions for GitHub Copilot.

When Copilot runs your custom agent as a subagent—to handle part of a larger task—the subagent does not follow your repository's custom instructions by default. This keeps the subagent focused on the specific task it was given.

If you want a subagent to follow your repository's conventions—for example, an agent that reviews or edits code—add include-custom-instructions: true to the agent file's frontmatter:

---
name: RepoAwareReviewer
description: Reviews a change against this repository's conventions
tools: ["*"]
include-custom-instructions: true
---

Review the change and flag anything that violates the repository's conventions.

Note

This setting only affects the agent when it runs as a subagent. A custom agent that you select yourself—with --agent, /agent, or by inference—already follows your repository's custom instructions, so the setting has no effect in that case.

For more information, including how this setting interacts with the --no-custom-instructions option, see GitHub Copilot CLI command reference.

Further reading