Creating a custom agent profile for a repository

1. Navigate to the agents tab athttps://github.com/copilot/agents.

2. Using the dropdown menu in the prompt box, select the repository you want to create the custom agent profile in.

   Note

   Organization and enterprise owners can create organization and enterprise-level custom agents that are available across all repositories within their organization or enterprise. For more information, seePreparing to use custom agents in your enterprise andPreparing to use custom agents in your organization.

3. Optionally, select the branch you want to create the agent profile in. The default is the main branch.

4. Click, then click Create an agent.

5. An agent profile template calledmy-agent.md will open in the.github/agents directory of the repository you chose. Edit the filename and configure the agent profile, including the name, description, tools, and prompts. For more information on what the agent profile can include, see the section below.

6. Commit the file to the repository. Go back to the agents tab and refresh the page if needed. Your custom agent will now appear in the dropdown when you click in the prompt box.

Configuring an agent profile

An agent profile is a Markdown file with YAML frontmatter that specifies the custom agent's name, description, available tools, and MCP server configurations (for organization/enterprise level agents). Configuring an agent profile involves defining the agent's identity, capabilities, tool access, and behavioral instructions.

For detailed configuration information about YAML properties, tools, MCP server setup, tool aliases, and how custom agents are processed, seeCustom agents configuration.

To configure your agent profile:

1. Choose aname for your custom agent. Select a unique, descriptive name that identifies the agent's purpose.
2. Write a briefdescription explaining what your agent does and its specific capabilities or domain expertise.
3. In thetools property, define which tools the agent can use. This is a list of tool names or aliases, including tools from MCP servers configured in the repository settings or the agent profile (for example,tools: ["read", "edit", "search", "some-mcp-server/tool-1"]). If you omit this property, the agent will have access to all available tools.
4. If creating an organization or enterprise level agent, you can use themcp-servers property to optionally configure MCP servers that will be available only to this agent to extend its capabilities.
5. Write the agent's prompt. Define the agent's behavior, expertise, and instructions in the Markdown content below the YAML frontmatter.

Example agent profiles

The following examples demonstrate what an agent profile could look like for the common tasks of writing tests or planning the implementation of a project. For additional inspiration, see theCustom agents examples in the customization library. You can also find examples in theawesome-copilot community collection, though note that the community examples are designed for VS Code chat modes, so the syntax may differ slightly from the custom agents syntax.

Testing specialist

This example enables all tools by omitting thetools property.

---name: test-specialistdescription: Focuses on test coverage, quality, and testing best practices without modifying production code---You are a testing specialist focused on improving code quality through comprehensive testing. Your responsibilities:- Analyze existing tests and identify coverage gaps- Write unit tests, integration tests, and end-to-end tests following best practices- Review test quality and suggest improvements for maintainability- Ensure tests are isolated, deterministic, and well-documented- Focus only on test files and avoid modifying production code unless specifically requestedAlways include clear test descriptions and use appropriate testing patterns for the language and framework.

---name: test-specialistdescription: Focuses on test coverage, quality, and testing best practices without modifying production code---You are a testing specialist focused on improving code quality through comprehensive testing. Your responsibilities:- Analyze existing tests and identify coverage gaps- Write unit tests, integration tests, and end-to-end tests following best practices- Review test quality and suggest improvements for maintainability- Ensure tests are isolated, deterministic, and well-documented- Focus only on test files and avoid modifying production code unless specifically requestedAlways include clear test descriptions and use appropriate testing patterns for the language and framework.

Implementation planner

This example only enables a subset of tools.

---name: implementation-plannerdescription: Creates detailed implementation plans and technical specifications in markdown formattools: ["read", "search", "edit"]---You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:- Analyze requirements and break them down into actionable tasks- Create detailed technical specifications and architecture documentation- Generate implementation plans with clear steps, dependencies, and timelines- Document API designs, data models, and system interactions- Create markdown files with structured plans that development teams can followAlways structure your plans with clear headings, task breakdowns, and acceptance criteria. Include considerations for testing, deployment, and potential risks. Focus on creating thorough documentation rather than implementing code.

---name: implementation-plannerdescription: Creates detailed implementation plans and technical specifications in markdown formattools: ["read", "search", "edit"]---You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:- Analyze requirements and break them down into actionable tasks- Create detailed technical specifications and architecture documentation- Generate implementation plans with clear steps, dependencies, and timelines- Document API designs, data models, and system interactions- Create markdown files with structured plans that development teams can followAlways structure your plans with clear headings, task breakdowns, and acceptance criteria. Include considerations for testing, deployment, and potential risks. Focus on creating thorough documentation rather than implementing code.

Using custom agents

Once you've created a custom agent, you can use it wherever Copilot coding agent is available.

• When prompting Copilot coding agent with a task on GitHub.com, use the dropdown menu in the agents panel or agents tab to select your custom agent instead of the default coding agent.
• When assigning Copilot coding agent to an issue, you can select your custom agent from the dropdown menu to handle the issue with your specialized configuration.
• When using the GitHub Copilot CLI, you can choose to use a particular custom agent by using the/agent slash command or referencing the agent in a prompt or via a command-line argument. For more information, seeUsing GitHub Copilot CLI.

When Copilot opens pull requests, it will note which custom agent was used to complete the work in the pull request description.

For more information on using Copilot coding agent, seeAsking GitHub Copilot to create a pull request.

Using custom agents as VS Code chat modes

You can also use your custom agent profiles directly in Visual Studio Code as chat modes. In VS Code, you switch between chat modes using the mode dropdown in the Chat view, allowing you to access specialized configurations for different tasks like planning, code editing, or research. For more information, seeUse chat modes in VS Code.

Note that some properties may function differently between the GitHub.com and VS Code environments. For more information, seeCustom agents configuration.

Next steps

• For a hands-on tutorial to create your first custom agent, seeYour first custom agent.
• For detailed configuration information, seeCustom agents configuration.
• For information on using coding agents, including your custom agents, to create pull requests, seeAsking GitHub Copilot to create a pull request.