How to Build a Custom GitHub Copilot Agent (Step by Step)

To build a custom GitHub Copilot agent, you create a Markdown file that ends in .agent.md, put it in the .github/agents folder of your repository, and fill it with YAML frontmatter (a required description, plus optional name, tools and model) and a prompt that tells the agent how to behave. Once the file is in place, you pick the agent from the agents dropdown in your IDE, or from the agents tab on GitHub.com after you merge it into the default branch. This guide walks through every step with working examples, based on GitHub's current documentation.

What is a custom agent in GitHub Copilot?

GitHub describes custom agents as "specialized versions of the Copilot agent that you tailor to particular tasks and workflows." Each one lives in a file called an agent profile. The profile sets the agent's purpose, gives it instructions, and can limit which tools it may use.

You can use the same profile in several places:

• Copilot cloud agent on GitHub.com (the agents tab, issue assignment and pull requests)
• GitHub Copilot CLI
• Visual Studio Code, Visual Studio, JetBrains IDEs, Eclipse and Xcode

Custom agents in JetBrains IDEs, Eclipse and Xcode are in public preview, so expect some changes there.

A quick note on names. If you read older tutorials, you will see "custom chat modes" and .chatmode.md files. VS Code now calls these custom agents. Its docs tell you to rename .chatmode.md files to .agent.md and move them to a supported agent folder. Also, "Copilot coding agent" was renamed to "Copilot cloud agent" in April 2026.

Where do custom agent files go?

The folder decides who can use the agent.

If two agents share a name, the lowest level wins. A repository agent overrides an organization agent, and an organization agent overrides an enterprise agent. The name match uses the file name without .md or .agent.md.

How to build a custom GitHub Copilot agent step by step

Step 1: Create the agent file

Pick the route that matches where you work.

1. In VS Code: open Copilot Chat. In the agents dropdown at the bottom of the chat view, click Configure Custom Agents..., then Create new custom agent. You can also run Chat: New Custom Agent from the Command Palette. Choose Workspace to save it in .github/agents, or User profile to use it in all your workspaces.
2. On GitHub.com: go to the agents tab at github.com/copilot/agents, select a repository, click the Copilot icon, then Create an agent. This opens a template named my-agent.agent.md in .github/agents.
3. By hand: create the file yourself.

mkdir -p .github/agents
touch .github/agents/test-specialist.agent.md

File names may only use letters, numbers, ., - and _. Give the file a clear, unique name, because the text before .agent.md becomes the default agent name.

Step 2: Write the frontmatter

The frontmatter sits between two --- lines at the top of the file. Here are the properties GitHub documents:

The old infer property is retired. Use disable-model-invocation and user-invocable instead.

---
name: test-specialist
description: Improves test coverage and test quality without changing production code.
tools: ["read", "search", "edit", "execute"]
---

Step 3: Write the agent's prompt

Everything below the frontmatter is the prompt. It can be up to 30,000 characters. Write it like a brief for a new teammate: role, scope, rules and output format.

You are a testing specialist for this repository.

## Your job
- Find code paths that have no tests.
- Write focused unit tests that follow the existing test style.
- Run the test suite and fix failing tests you created.

## Rules
- Never edit files outside test folders.
- If a fix needs a production code change, stop and explain why.
- Keep each test small and name it after the behavior it checks.

Step 4: Limit the agent's tools

Fewer tools means safer, more predictable agents. A planning agent, for example, rarely needs to run shell commands. GitHub supports these tool aliases, and they are not case sensitive:

Some useful patterns:

• tools: ["*"] or no tools line gives every tool.
• tools: [] turns all tools off.
• github/* enables every tool from the built-in GitHub MCP server.
• some-mcp-server/some-tool enables one MCP tool.

Unknown tool names are ignored, so check spelling if a tool seems missing.

Step 5: Add MCP servers (optional, cloud agent and CLI)

You can give one agent its own MCP server in the frontmatter. This is GitHub's documented shape. Note that VS Code and other IDE custom agents ignore mcp-servers.

---
name: my-custom-agent-with-mcp
description: Custom agent description
tools: ['tool-a', 'tool-b', 'custom-mcp/tool-1']
mcp-servers:
  custom-mcp:
    type: 'local'
    command: 'some-command'
    args: ['--arg1', '--arg2']
    tools: ["*"]
    env:
      ENV_VAR_NAME: ${{ secrets.COPILOT_MCP_ENV_VAR_VALUE }}
---

Secrets come from Agents secrets in your repository or organization, and their names must start with COPILOT_MCP_.

Step 6: Commit and merge

For VS Code, the agent shows up as soon as the file is saved. For Copilot cloud agent on GitHub.com, commit the file and merge it into the default branch. Then refresh the agents tab.

git add .github/agents/test-specialist.agent.md
git commit -m "Add test-specialist custom agent"
git push

GitHub versions agent profiles by Git commit SHA. New tasks use the latest version, while an existing pull request keeps the version it started with.

Step 7: Run your custom agent

• VS Code: pick the agent from the agents dropdown at the bottom of the chat view, then type your task.
• GitHub.com: open the agents tab, pick the agent in the prompt box dropdown, and start a task. You can also choose the agent when you assign an issue to Copilot.
• Copilot CLI: use the /agent command, mention the agent in your prompt, or pass it as a command-line argument.

Pull requests created this way note which custom agent did the work.

Step 8: Test and improve

Start with a small, low-risk task. Read what the agent did, then tighten the prompt or the tool list. In VS Code, select Configure Custom Agents from the dropdown and click your agent to edit it.

Custom agent vs custom instructions: which do you need?

They solve different problems.

Use instructions for things every request should know. Use a custom agent when you want a specialist, like a planner that can only read and search. For simple task-specific guidance, GitHub suggests a skill instead of a full agent.

Example: a read-only planning agent

GitHub's docs include an implementation planner that only has read, search and edit tools. Here is a similar profile you can copy:

---
name: implementation-planner
description: Writes implementation plans and technical specs in Markdown. Does not change source code.
tools: ["read", "search", "edit"]
---

You create implementation plans. For each request:
1. Read the relevant code and summarize how it works today.
2. List the files that must change and why.
3. Break the work into small, testable steps.
4. Save the plan as a Markdown file in docs/plans/.

Do not edit source code. Only create or update files in docs/plans/.

Frequently asked questions

Where do I put a custom agent file for GitHub Copilot? For one repository, use .github/agents/NAME.agent.md. For personal use across projects, use ~/.copilot/agents/. For an organization, use the agents folder at the root of the org's .github or .github-private repository.

Which frontmatter fields are required in an .agent.md file? Only description is required. name, tools, model, target and the others are optional. If you leave out tools, the agent can use every available tool.

Why does my custom agent not show up on GitHub.com? The file has to be merged into the repository's default branch. After merging, refresh the agents tab. Also check the file name only uses letters, numbers, ., - and _.

Can a custom agent use MCP servers? Yes. You can reference MCP tools in tools with the server/tool format. You can also define servers in mcp-servers, but that property is ignored by VS Code and other IDE custom agents.

Are custom chat modes the same as custom agents? Yes. VS Code says custom agents were previously known as custom chat modes. Rename .chatmode.md files to .agent.md and move them into a supported agents folder.

How long can the agent prompt be? The Markdown body of the profile can be up to 30,000 characters.

Keep learning

• Not sure where your agent should run? Read Copilot agent mode vs Copilot coding agent: what's the difference?
• Want to give your agent new tools? Read How to connect MCP servers to GitHub Copilot
• Build real agents with guided lessons in the free course GitHub Copilot Agents from Scratch.

Sources

• About custom agents (GitHub Docs)
• Creating custom agents for Copilot cloud agent (GitHub Docs)
• Using custom agents in your IDE (GitHub Docs)
• Custom agents configuration reference (GitHub Docs)
• Your first custom agent (GitHub Docs)
• Adding repository custom instructions (GitHub Docs)
• Custom agents in VS Code (VS Code Docs)
• Research, plan, and code with Copilot cloud agent (GitHub Changelog)