Why custom agents are different

Custom instructions shape defaults and prompt files package one-off workflows, but custom agents define persistent specialist behavior.

A custom agent can encode:

  • Role and expertise
  • Tool boundaries
  • Model preferences
  • MCP-backed capabilities
  • Environment targeting

This makes custom agents the right choice for complex, repeatable workflows where persona and permissions must be stable.

Use cases

  • Teams needing specialist Copilot behavior beyond one-off prompts
  • Repository maintainers who need strict tool boundaries
  • Developers deciding whether a prompt file or a custom agent fits their workflow

Step 1: Understand agent profile anatomy

A custom agent profile is a Markdown file with YAML frontmatter and instruction body.

Typical fields:

  • name (optional)
  • description (required)
  • target (optional)
  • tools (optional)
  • model (optional)
  • disable-model-invocation or user-invocable controls
  • mcp-servers (optional, environment-dependent)

Then the Markdown body defines behavioral instructions.

Minimal profile

---
name: readme-specialist
description: Improve README files and documentation consistency
tools: ["read", "search", "edit"]
---

You are a documentation specialist.
- Focus on README and docs files
- Keep content scannable and accurate
- Do not modify source code files unless asked

Step 2: Place the profile at the right scope

Common locations from docs:

  • Repository-level custom agents in .github/agents/
  • Organization and enterprise variants in .github-private governance repositories, using root-level agents directories where supported

Use repository scope first unless you already have stable standards to share organization-wide.

How to invoke a custom agent

On GitHub.com:

  1. Open a repository and click the Copilot icon to open the chat panel.
  2. In the agent picker (the dropdown next to the chat input), select your agent by name.
  3. Ask your question normally. The agent's instruction body and tool restrictions are active for the entire session.

In VS Code:

  1. Open the Copilot Chat panel.
  2. Click the agent selector at the top of the chat pane and choose your custom agent from the list.
  3. All prompts sent in that session use the agent's profile.

Agents with disable-model-invocation: true only appear when explicitly selected. Agents without this flag may be invoked automatically by Copilot when it determines the agent's description matches the task — which is useful for broadly applicable agents but risky for tightly scoped ones.

Step 3: Control tool exposure deliberately

The tools field is central to safety and reliability.

Behavior summary:

  • Omitted tools means all available tools can be used
  • tools: [] disables tools
  • tools: [list] enables only specified tools

You can include aliases and namespaced tools, including MCP server tools.

Diagram: Safe tool narrowing

+----------------------------+
| Define custom agent task   |
+----------------------------+
             |
             v
+----------------------------+
| Identify minimum tool set  |
+----------------------------+
             |
             v
+----------------------------+
| Restrict tools in profile  |
+----------------------------+
             |
             v
+----------------------------+
| Validate outputs and logs  |
+----------------------------+

Step 4: Add MCP servers only when needed

Custom agents can reference MCP servers for external capabilities in supported environments.

Use MCP when the agent must interact with external systems or specialized tooling. Avoid adding MCP servers by default if core repository tools are sufficient.

From official guidance, MCP configuration can include environment variables and secret references with supported syntax variants.

Step 5: Decide manual selection vs model invocation

Two frontmatter fields control how an agent is invoked:

Field Value Effect
disable-model-invocation true Copilot will never auto-select this agent; it only runs when the user explicitly picks it.
disable-model-invocation false (default) Copilot may auto-select this agent when it determines the task matches the description.
user-invocable true Agent appears in the agent picker for manual selection.
user-invocable false Agent does not appear in the picker; model can still invoke it if disable-model-invocation is false.

For most teams, the safest starting pattern is:

user-invocable: true
disable-model-invocation: true

This makes the agent available to users through the picker but never activates it automatically. Expand to model invocation only for agents whose scope is broad enough that automatic activation adds consistent value rather than noise.

Note: infer is a retired property in older profiles. Replace it with disable-model-invocation.

Step 6: Reuse proven patterns from the 4 library examples

The custom agent tutorial set includes four strong archetypes.

Example Core role Typical adaptation
Your first custom agent Documentation specialist README and docs quality gates
Implementation planner Planning and scoping specialist Feature plan generation before coding
Bug fix teammate Focused fix implementation Root-cause-first bug remediation
Cleanup specialist Maintainability specialist Targeted codebase cleanup and deduplication

Step 7: Build an operating loop for agent quality

Use this practical loop:

  1. Define one narrow agent purpose
  2. Restrict tools to minimum required
  3. Run agent on 3 representative tasks
  4. Review logs, PR quality, and rework rate
  5. Refine prompt and tool list

Avoid monolithic agents that attempt to do everything.

Step 8: Track sessions and audit behavior

Session tracking is part of operating custom agents safely at scale.

You can inspect session status and logs across supported surfaces such as:

  • GitHub agents tab/panel
  • GitHub CLI command set for agent tasks
  • IDE integrations

Logs are useful for understanding why a change was made and for post-incident analysis.

Step 9: Plan for versioning and override behavior

Agent behavior is tied to profile versions in repository history. In multi-level setups, lower-level definitions can override higher-level definitions when names conflict.

Treat profile updates as controlled changes:

  • PR review required
  • changelog notes for behavior changes
  • rollback plan for critical regressions

Step 10: End-to-end lab

Use this lab to create one narrow agent and evaluate whether it improves plan quality.

Goal

Create a planning-only custom agent that cannot run broad tooling.

Create agent profile

Path: .github/agents/implementation-planner.agent.md

---
name: implementation-planner
description: Creates scoped implementation plans with risks and validation
tools: ["read", "search", "edit"]
user-invocable: true
disable-model-invocation: true
---

You are a planning specialist.

Always return:
- Problem statement
- Constraints and assumptions
- Phased plan
- Test strategy
- Rollback strategy

Do not generate production code unless explicitly requested.

Run the lab

  1. Select the custom agent in GitHub.com agents UI or IDE agent picker.
  2. Prompt: "Plan migration from REST v1 to v2 for user search endpoint."
  3. Verify the response is planning-focused and does not drift into broad implementation.

Quality checks

  • Plan includes risks and validation checkpoints.
  • Tool usage remains scoped to planning needs.
  • Output is reusable as a PR planning artifact.

Key takeaways

  • Custom agents are the right abstraction for specialist, repeatable, tool-aware workflows.
  • Keep each agent narrow in purpose and constrained in tools.
  • Introduce MCP integrations only where they add clear capability value.
  • Use session logs and versioned profile changes as part of governance.
  • Build multiple small agents instead of one oversized generalist.


References