GitHub Copilot

GitHub Copilot custom agents: .github/agents/*.agent.md profiles, tools and frontmatter

How do I create a custom agent for GitHub Copilot in .github/agents?

Add a Markdown file ending in .agent.md to .github/agents with YAML frontmatter that includes a required description, then merge it to the default branch. The body is the agent's prompt, up to 30,000 characters. Select it from the agents dropdown on GitHub, when assigning an issue, or with /agent in Copilot CLI.

Where the file goes

  • Repository: .github/agents/NAME.agent.md
  • Organization level: an agents folder at the root of the org's .github or .github-private repository.
  • File names may only use . - _ a-z A-Z 0-9.
  • The agent appears after you merge the file into the default branch.

Example profile

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

---
name: implementation-planner
description: Creates detailed implementation plans and technical specifications in markdown format
tools: ["read", "search", "edit"]
---

You are a technical planning specialist focused on creating comprehensive implementation plans. Your responsibilities:
- Analyze requirements and break them down into actionable tasks
- Create detailed technical specifications and architecture documentation
- Generate implementation plans with clear steps, dependencies, and timelines

Frontmatter properties

  • description: required.
  • name: optional. Defaults to the file name without .agent.md.
  • target: vscode or github-copilot. Unset means both.
  • tools: list or comma separated string. Unset means all tools.
  • model: model to use. Unset inherits the default.
  • disable-model-invocation: true means the agent must be picked manually. Default false.
  • user-invocable: false hides it from manual selection. Default true.
  • mcp-servers and metadata: not used by VS Code and other IDE agents.
  • infer is retired.

Tools and aliases

  • Omit tools or use ["*"] for all tools. Use [] for no tools.
  • MCP tools: some-mcp-server/some-tool, or some-mcp-server/* for all tools from one server.
  • Aliases (case insensitive): execute, read, edit, search, agent, web, todo.
  • web is not currently applicable for the cloud agent. todo is not supported in the cloud agent.
  • Unrecognized tool names are ignored.

Use the agent

  • On GitHub: pick it from the dropdown in the agents panel or agents tab.
  • On an issue: choose it when assigning Copilot.
  • In Copilot CLI: use the /agent slash command, mention it in a prompt, or pass it as a command line argument.

Custom agents are in public preview for JetBrains IDEs, Eclipse and Xcode.

Sources

GitHub Docs: Creating custom agents for Copilot cloud agentGitHub Docs: Custom agents configuration

More on GitHub Copilot

GitHub Copilot standards support

Other guides

Cursor: allow all terminal commandsClaude Code: allow commands without promptsCodex CLI: approval and sandbox modesGemini CLI: YOLO mode, auto_edit and allowing specific shell commandsCursor Privacy Mode: telemetry, training and data retentionClaude Code telemetry and data retention: what is sent and how to turn it offGemini CLI: turn off usage statistics and telemetryCLAUDE.md: where it goes, how it loads, and how it works with AGENTS.mdClaude Code hooks: format on save, block risky edits, get notifiedClaude Code subagents: create one, limit its tools, and call itAdd MCP servers to Cursor with mcp.json: Keep files out of Cursor with .cursorignore: Configure Codex with config.toml: Configure Gemini CLI with settings.json: Add MCP servers to Claude Code (claude mcp add, .mcp.json, scopes): Claude Code custom slash commands and skills (SKILL.md): GitHub Copilot custom instructions: Adding MCP servers to GitHub Copilot: Claude Code settings.json: file locations, precedence, and key settingsClaude Code plugins and marketplaces: install, create, and shareGemini CLI extensions and custom commands: Configuring OpenCode with opencode.json: Cline Rules: workspace, global, and conditional rulesKiro steering files: .kiro/steering, inclusion modes, and AGENTS.mdZed agent: instruction files, MCP servers, tool permissions, and ACP agentsCursor CLI: install, headless mode, permissions and CIAider: CONVENTIONS.md, .aider.conf.yml and API keysJunie guidelines, MCP and the Action Allowlist: Amp AGENTS.md, settings.json and MCP: Configure Goose extensions, hints, recipes and permissions: Customize OpenHands with skills, AGENTS.md, setup.sh and MCP: Configure Factory Droid CLI: AGENTS.md, settings.json, autonomy, custom droids and MCPConfigure Qwen Code: settings.json, providers, QWEN.md, MCP and approval modesCursor hooks: hooks.json, beforeShellExecution, afterFileEdit and exit codesCursor sandbox: sandbox.json, network allowlist and run modesCursor settings: settings.json, Cursor Settings and the ~/.cursor config filesCursor browser agent: @browser, browser automation and approval modesCursor subagents: .cursor/agents, frontmatter, built-in Explore, Bash and BrowserCursor telemetry and OpenTelemetry export (Privacy Mode, OTLP, Analytics API): Cursor rules setup: .cursor/rules, .mdc frontmatter, globs, alwaysApply and AGENTS.mdClaude Code headless mode: claude -p, --output-format json, --bare and CI flagsClaude Code statusline: custom status bar in settings.json with context %, cost and git branchClaude Code /model: switch models, aliasesClaude Code /cost and /usage: check token spend, usage limits and reduce costsClaude Code VS Code extension: install, shortcuts, settings and /ideCodex AGENTS.md: global, project and override instruction files explainedCodex MCP servers: codex mcp add and [mcp_servers] in config.tomlCodex sandbox modes: read-only, workspace-write, danger-full-access and network accesscodex exec: run Codex non-interactively in scripts and CI with JSON outputCodex skills: create SKILL.md, skill folder locations and $skill invocationGEMINI.md in Gemini CLI: context file locations, imports and /memoryGemini CLI MCP servers: gemini mcp add and mcpServers in settings.jsonGemini CLI custom slash commands: TOML files, {{args}}, !{shell} and @{file}Gemini CLI headless mode: gemini -p, JSON output and exit codes for scripts and CIGemini CLI sandbox: enable Docker, Podman, macOS Seatbelt or gVisorcopilot-setup-steps.yml: set up the GitHub Copilot cloudGitHub Copilot CLI permissions: --allow-tool, --deny-tool, --allow-all-tools and trusted directoriesGitHub Copilot code review settings: automatic PR reviews, rulesets, effort level and approvals

Get the weekly agent stack update

New official MCP servers, spec changes and harness releases, checked against the source. One email a week, no fluff.

Reviewed Oct 13, 2026. Settings change often; the linked vendor docs are the source of truth.