github-copilot-custom-agents

Create a .agent.md file in .github/agents/ with frontmatter defining name, description, tools, and invocation flags. Define the role, non-goals, allowed mutations, and exit condition first, then grant least-privilege tools and verify the agent appears in the intended host.

List only the required tools in the agent's tools field, giving planning or audit roles read-only search tools. Editing or terminal tools require a stated job, and tool restriction reduces capability but is not a security boundary for model output.

Current fields include name, description, argument-hint, tools, agents, model, user-invocable, disable-model-invocation, target, and handoffs. The mcp-servers field applies to the GitHub Copilot target rather than normal VS Code configuration, so inspect the active schema before emitting fields.

Do not create an agent for a single slash command, automatic coding rules, Agent Skills, or merely changing the selected chat model. A custom agent is justified only when its instructions and capability boundary recur across tasks.

Handoffs auto-submit when send is not set to false, and fail when the target agent does not resolve in the active host. Set send: false by default, verify every handoff target, and test picker visibility and model invocation separately.