In GitHub Copilot, a custom agent is a Copilot agent defined by a Markdown file — an agent profile — rather than relying on generic behaviour. The profile describes the agent’s role and area of expertise, which tools it can access, the standards and guardrails it must follow and the outputs it should produce, with the stated result that the agent behaves consistently wherever it runs. GitHub presents it as a way to make a general coding agent into a specialized one: where a generic agent might suggest how to clean up code, a custom agent applies a team’s own formatting rules, tooling, accessibility standards, review requirements and safety requirements every time.
Usage
An agent profile is a Markdown file with YAML frontmatter — fields such as name, description,
tools and, in one of GitHub’s examples, model — followed by the agent’s instructions. In
GitHub Copilot CLI, a profile is added to the .github/agents directory of a
repository with a filename ending in .agent.md, and the agent is selected with the /agent slash
command. Because the profile lives in the repository, GitHub’s framing is that a team can review,
version and share it like code, so the same expectations follow the work from the terminal to the IDE
and into pull requests.
GitHub distinguishes custom agents a team writes from off-the-shelf agents built with partners such as JFrog, Dynatrace, Octopus Deploy and Arm. It recommends the partner agents for trying a working agent with minimal setup and for tool-specific best practices, and the team’s own custom agents where a team needs its conventions, internal tooling and exact stack followed every time — noting that teams often start from a partner agent and adapt it. Its examples of workflows suited to the mechanism are security audits, infrastructure-as-code compliance reviews, release notes and incident first-look reports (From one-off prompts to workflows: How to use custom agents in GitHub Copilot CLI).