GitHub Copilot custom agents are reusable Markdown profiles that give Copilot a focused role, prompt and tool set. In Copilot CLI, a project agent lives in .github/agents/ and a personal agent lives in ~/.copilot/agents/; each file uses the .agent.md extension. The minimum useful profile is YAML frontmatter with a required description, followed by the instructions the agent should follow.
Applies to: GitHub Copilot CLI and Copilot custom agents. Documentation checked October 14, 2026.
On this page
A minimal custom agent
Create .github/agents/security-reviewer.agent.md in the repository:
---
name: security-reviewer
description: Reviews changed code for security risks without editing production files
tools: ["read", "search"]
---
Review the requested files for exposed secrets, injection risks,
authentication bypasses and unsafe dependency use.
Return findings with the affected file, evidence, severity and a
specific remediation. Do not edit files.
GitHub defines an agent profile as Markdown with YAML frontmatter. The frontmatter configures the agent; the Markdown below it is the prompt that sets its behavior and constraints. The description is required because Copilot uses it to understand when the agent is relevant. name and tools are optional (GitHub’s custom-agent configuration reference).
Keep routing language in description—what the agent is for and when it should be used—and put the operating procedure in the body. “Helps with code” is too vague to guide selection.
Where Copilot CLI loads agent files
GitHub’s CLI instructions document two locations (creating custom agents for Copilot CLI):
| Scope | File location | Use it for |
|---|---|---|
| Project | .github/agents/NAME.agent.md | Conventions and workflows for one repository |
| User | ~/.copilot/agents/NAME.agent.md | A personal specialist available in every repository |
If an agent with the same name exists in both locations, the user-level profile takes precedence in Copilot CLI. Restart the CLI after adding a profile so it loads the file.
GitHub also supports organization- and enterprise-level custom agents. Organization profiles live under /agents/ in the organization’s .github or .github-private repository. Enterprise profiles go in the .github-private repository selected in enterprise settings (about custom agents).
For a team, repository scope is the practical default: the profile is reviewed beside the code and can name real project paths.
The fields that change behavior
The configuration reference lists these main frontmatter fields:
description: required; explains the agent’s purpose and capabilities.name: optional display name. Without it, the filename identifies the agent.tools: limits built-in and MCP tools. Omitting it enables all available tools;tools: []enables none.model: selects a model. If omitted, the current default is inherited.target:vscodeorgithub-copilot. Without it, the profile targets both environments.disable-model-invocation: settruewhen the agent must be selected manually rather than inferred from the task.user-invocable: setfalsewhen users should not select the agent directly.mcp-servers: adds MCP configuration for Copilot cloud agent. GitHub says this property is not used by VS Code and other IDE custom agents.
The older infer field is retired; GitHub now points authors to disable-model-invocation and user-invocable.
The prompt can be up to 30,000 characters. A useful profile normally says what files the agent may touch, what evidence it should gather, what output it must return, and where it must stop.
Restrict tools deliberately
GitHub’s tool aliases include read, search, edit, execute, agent, web and todo, although availability differs between the cloud agent and IDEs.
A read-only reviewer can be narrow:
tools: ["read", "search"]
An implementation agent may need editing and tests:
tools: ["read", "search", "edit", "execute"]
Omitting tools or using ["*"] exposes every available built-in and configured MCP tool. An empty list disables all tools. MCP tools can be scoped by server, such as some-mcp-server/some-tool or some-mcp-server/*.
A documentation reviewer rarely needs shell execution. A planner may not need editing. Narrowing the list makes the intended boundary visible in review.
Add MCP tools only where the agent needs them
Custom-agent frontmatter can contain an mcp-servers block for Copilot cloud agent. The profile can then allow selected server tools:
---
name: issue-triage
description: Classifies new issues and links related repository history
tools: ["read", "search", "github/*"]
---
GitHub’s reference says the cloud agent has out-of-the-box GitHub and Playwright MCP servers. Custom MCP configuration accepts secret references such as ${{ secrets.NAME }} and variable references such as ${{ vars.NAME }}, when they are configured as Agents secrets or variables.
Do not put a token in an agent file. The profile is repository content; credentials belong in the repository or organization agent-secret settings. For the broader setup and approval model, see GitHub Copilot CLI: install, sign in and tool approvals.
How to invoke an agent
Copilot CLI supports four routes:
- Enter
/agentand choose the profile. - Ask for it by name: “Use the security-reviewer agent on the files in src/auth.”
- Let Copilot infer it from the profile’s description.
- Select it non-interactively:
copilot --agent security-reviewer --prompt "Review src/auth for security risks"
The value after --agent is the profile filename without .agent.md. GitHub recommends lowercase letters and hyphens for programmatic names.
Use explicit selection while validating a profile. For a sensitive or expensive workflow, set disable-model-invocation: true so it is never chosen automatically.
Precedence and duplicate names
GitHub deduplicates profiles by filename without the .md or .agent.md suffix. The cross-environment reference says the lowest configuration level wins: repository overrides organization, which overrides enterprise.
Copilot CLI’s personal directory is a separate case: its guide says a same-named profile in ~/.copilot/agents/ wins over the project copy. Avoid reusing a name at user and project scope unless that override is intentional.
Custom agents are not custom instructions
The features solve different problems:
- Custom instructions apply broadly to Copilot’s work in a repository. See Copilot custom instructions: files, paths and AGENTS.md.
- A custom agent is selected for a particular task and can have its own tool boundary.
- Hooks run at lifecycle events rather than defining a specialist. See Copilot hooks: config files, events and examples.
If every task should follow a rule, put it in custom instructions. If only database migrations, documentation reviews or threat checks need a procedure, use an agent profile.
Review checklist
Before committing a profile:
- Give it one job that can be recognized from the description.
- Name the files or areas it may edit.
- State the output format and stop conditions.
- Remove tools it does not need.
- Keep credentials out of the file.
- Test explicit selection before relying on inference.
- Check for same-named profiles at every scope.
- Review the profile like code.
GitHub versions repository profiles by Git commit SHA. When a custom agent is assigned to a task, Copilot uses the latest profile for that repository and branch; interactions on the resulting pull request keep the same version for consistency (configuration reference).
