About custom agents

Custom agents enhance Copilot coding agent with specialized assistance tailored to your needs.

Who can use this feature?

Copilot coding agent is available with the GitHub Copilot Pro, GitHub Copilot Pro+, GitHub Copilot Business and GitHub Copilot Enterprise plans. The agent is available in all repositories stored on GitHub, except repositories owned by managed user accounts and where it has been explicitly disabled.
Sign up for Copilot

In this article

About custom agents

Custom agents are specialized versions of Copilot coding agent that you can tailor to your unique workflows, coding conventions, and use cases. Instead of repeatedly providing the same instructions and context, custom agents allow you to define specialized agents that act like tailored teammates—following standards, using the right tools, and implementing team-specific practices.

Custom agents are defined using Markdown files, called agent profiles, that specify prompts, tools, and MCP servers. This allows individuals and teams to encode their conventions, frameworks, and desired outcomes directly into Copilot. The agent profile serves as the artifact that defines the custom agent's behavior, and assigning the agent to a task or issue instantiates the custom agent.

Agent profile format

Agent profiles are Markdown files with YAML frontmatter. In their simplest form, they include:

  • Name: A unique identifier for the custom agent
  • Description: Explains the agent's purpose and capabilities
  • Prompt: Custom instructions that define the agent's behavior and expertise
  • Tools: Specific tools the agent can access. This is optional, and the default is access to all available tools, including built-in tools and MCP server tools.

Organization and enterprise-level agent profiles can also include MCP server configurations within the agent profile, using the mcp-server property.

Example agent profile

This is a basic agent profile with name, description, and prompt configured.

---
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 custom agents

You can define agent profiles at the repository level (.github/agents/CUSTOM-AGENT-NAME.md in your repository) for project-specific agents, or at the organization or enterprise level (/agents/CUSTOM-AGENT-NAME.md in a .github-private repository) for broader availability. See Preparing to use custom agents in your organization and Preparing to use custom agents in your enterprise.

Where you can use custom agents

Note

Custom agents are in public preview for JetBrains IDEs, Eclipse, and Xcode, and subject to change.

Once created, your custom agents are available wherever you can use Copilot coding agent, including GitHub.com (the agents tab and panel, issue assignment, pull requests), the GitHub Copilot CLI, and in Visual Studio Code, JetBrains IDEs, Eclipse, and Xcode.

Agent profiles can be used directly in Visual Studio Code, JetBrains IDEs, Eclipse, and Xcode, though some properties may function differently, or be ignored, between environments.

For more information on using custom agents in Visual Studio Code specifically, see Custom agents in VS Code in the VS Code documentation.

Next steps

To start creating your own custom agents, see Creating custom agents.