GitHub’s new custom agent system is one of the more important coding-agent shifts of 2026 because it turns agent behavior into a reusable project asset instead of a one-off prompt. The key file is .agent.md, and it gives teams a structured way to define specialist Copilot agents for repeatable work like code review, documentation, migrations, security checks, and internal workflow enforcement.
That matters because many coding-agent experiments break down at exactly the point where teams need consistency. A single general-purpose agent can be helpful, but engineering organizations usually need repeatable specialist behavior tied to repositories, tools, and internal rules. GitHub’s custom agent model is a step toward that.
What .agent.md actually is
A .agent.md file is a Markdown-based agent profile that defines a specialized Copilot agent. GitHub documents custom agents as named agent profiles that can be created at the repository level inside .github/agents/, or at broader organizational scope through a .github-private repository. In practice, that means teams can turn recurring expertise into versioned files that live alongside their code and workflow conventions.
The important detail is that these files are not just loose instructions. A custom agent can include a name, description, tool access, and behavior guidance, which makes it more operational than an ordinary prompt. In GitHub Copilot CLI, custom agents can also be created interactively and stored either in the project or in a user directory, which makes them practical for both team-wide and personal workflows.
.agent.md vs AGENTS.md: not the same thing
This distinction is where a lot of confusion will come from.
AGENTS.md is emerging as a broader open convention for telling coding agents how to behave inside a repository. It acts more like a project instruction file. By contrast, GitHub’s .agent.md files define selectable custom agents with their own specialties.
So the difference is not just syntax. It is intent.
AGENTS.mdtells agents how the project works..agent.mddefines a named specialist agent for a particular kind of work.
That makes .agent.md more comparable to an internal library of reusable expert roles. A team could have a security-review agent, a README agent, a migration agent, and a release-notes agent, each designed for a different workflow.
Where GitHub custom agents run
GitHub’s documentation makes clear that custom agents are not limited to one surface. Once created, they can be used by Copilot cloud agent on GitHub.com, Copilot cloud agent in supported IDEs, and GitHub Copilot CLI. GitHub also notes that support in JetBrains IDEs, Eclipse, and Xcode is in public preview, which shows that the company is treating custom agents as a cross-surface capability rather than a niche add-on.
That platform spread is the strategic point. If a team defines a useful specialist agent once, that agent can travel across the environments where work actually happens: issues, pull requests, the terminal, and the IDE. That is a much more enterprise-friendly direction than asking every developer to recreate the same prompt setup by hand.
GitHub’s March 2026 Visual Studio update pushed this idea further by adding custom agents as .agent.md files in the repository, along with agent skills and MCP governance controls. That combination matters because it links specialization, tool access, and admin policy into the same workflow layer.
How custom agents work in Copilot CLI
GitHub Copilot CLI adds another important detail: work performed by a custom agent is carried out using a subagent. In other words, the system can spin up a temporary specialist agent with its own context window to handle a task without cluttering the main agent’s working context.
That is more important than it sounds. One of the big problems with real coding-agent work is context pollution. When every task, instruction, and tool trace gets shoved into one running conversation, quality often drops. GitHub’s subagent approach gives teams a cleaner model: let the main agent coordinate, and let temporary specialists handle the detailed work.
For larger tasks, that starts to look less like an assistant and more like a lightweight multi-agent workflow. A developer or lead agent can route a documentation task to one specialist, a code review task to another, and preserve higher-level planning at the top layer.
Why this matters for engineering teams
Most companies do not need an endless menu of flashy agent demos. They need predictable behavior in the boring, high-frequency work that slows teams down every week. That is where custom agents become useful.
A well-designed .agent.md layer can help teams:
- standardize recurring coding and review workflows
- reduce prompt drift across engineers
- keep specialist instructions versioned with the repo
- control which tools an agent can use
- bring the same specialist behavior into GitHub.com, the CLI, and supported IDEs
There is also a governance angle here. As coding agents gain MCP connections and broader tool access, enterprises need a cleaner way to define what certain agents should do and what they should not do. Custom agents are not full governance by themselves, but they move teams closer to a controlled operating model for coding agents.
What to watch next
The bigger question is whether .agent.md becomes just a GitHub feature or part of a broader pattern in agent engineering. Right now, the trend is clear: coding platforms are shifting from one giant assistant toward collections of narrower, reusable agents with better-defined context and permissions.
If that continues, teams will care less about the raw model and more about how agent roles are packaged, shared, governed, and reused across workflows. GitHub custom agents are an early sign of that shift.
For technical teams, the practical takeaway is simple: if you already use Copilot, it is worth thinking about which repeated tasks deserve their own specialist agent file. The organizations that benefit most from coding agents in 2026 will not be the ones with the fanciest prompts. They will be the ones that turn proven workflows into reusable operating layers.