Copilot Agent Creator

Custom agents for GitHub Copilot are defined in .agent.md Markdown files called agent profiles. They encode a role, behavioral instructions, tool access, and optionally a model, without requiring extension development. The same profile can be used by Copilot cloud agent on GitHub.com, GitHub Copilot CLI, VS Code, JetBrains IDEs, Eclipse, and Xcode, but some properties only work on some surfaces.

[!IMPORTANT] This skill was last verified in November 2026 against GitHub Copilot CLI v1.0.105. Always verify against the official docs before relying on a property. The canonical references are:

• Custom agents configuration (GitHub)
• Custom agents in VS Code
• Custom agent file reference (VS Code)
• Copilot CLI custom agents reference

When to Use This Skill

• Creating a new custom agent profile for Copilot cloud agent, Copilot CLI, or VS Code
• Configuring tools, model, handoffs, subagents, hooks, or MCP servers in a profile
• Choosing the right scope (repository, user, organization, enterprise)
• Designing multi-agent workflows
• Writing effective agent prompts

Quick Decision Guide

Agent Profile Format

---
name: readme-creator
description: Agent specializing in creating and improving README files
tools: ["read", "search", "edit"]
---

You are a documentation specialist focused on README files. ...

description is the only required property (GitHub.com and Copilot CLI). In VS Code the YAML header is optional. The Markdown body holds the instructions and can be at most 30,000 characters.

[!TIP] For the full property reference and a per-surface compatibility table, load references/frontmatter-reference.md.

Where to Store Agent Profiles

VS Code's file-locations table lists .agent.md or .md files for .github/agents and ~/.copilot/agents; prefer .agent.md. The Local harness stores user-level agents in VS Code profile storage instead, separate from ~/.copilot/agents and ~/.claude/agents; move them to the folder the selected harness reads to reuse them.

The filename (minus .md / .agent.md) is the agent's ID and is used for deduplication. On name conflicts the lowest (most specific) level wins: repository over organization, organization over enterprise.

[!NOTE] In Copilot CLI, a user-level agent (~/.copilot/agents/) overrides a project agent with the same ID. The full priority order is in references/frontmatter-reference.md.

Tools

tools: ["read", "search"]          # specific tools (least privilege)
tools: ["*"]                       # all tools (same as omitting tools)
tools: []                          # no tools
tools: ["read", "my-server/*"]     # alias + all tools from an MCP server

Portable aliases: execute, read, edit, search, agent, web, todo. Unrecognized tool names are ignored, so one profile can list surface-specific tools. Apply least privilege: start read-only and add write/execute tools only when required.

[!TIP] For the alias table, VS Code tool names and the deprecated tool-set files, MCP namespacing, and CLI behavior, load references/tools-reference.md.

Model

model: Claude Sonnet 5                     # VS Code / IDEs: display name
model: ["Claude Opus 5", "GPT-5.5"]        # VS Code: prioritized fallback list
model: gpt-5.6-luna                       # Copilot CLI: model ID
reasoning-effort: high                     # VS Code, Copilot harness: low | medium | high | xhigh | max

Model names differ by surface (display names in VS Code, lowercase IDs in the CLI) and the model roster changes often. Check the supported models page, including its retirement table, before pinning a model.

Handoffs (VS Code / IDEs)

Ignored on GitHub.com's cloud agent. In VS Code they apply to the Local harness only. After a response, handoff buttons let the user switch to another agent with a pre-filled prompt.

handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Implement the plan outlined above.
    send: false

Subagents (VS Code and Copilot CLI)

In VS Code, a coordinating agent lists allowed subagents in agents and must include the agent tool:

tools: ["agent", "read", "search"]
agents: ["Researcher", "Implementer"]   # ["*"] or omit = all, [] = none

• user-invocable: false hides an agent from the picker (subagent/programmatic use only).
• disable-model-invocation: true stops other agents (VS Code) or the cloud agent (GitHub.com) from auto-selecting it. In VS Code, explicitly listing the agent in a coordinator's agents overrides this.
• In Copilot CLI, the main agent can run any custom agent as a subagent by inference. Add include-custom-instructions: true if the subagent should read AGENTS.md / copilot-instructions.md / CLAUDE.md.

Writing the Prompt Body

# Agent Name

You are a [role] focused on [domain]. Your scope is limited to [specific boundaries].

## Responsibilities

- [What it does]
- [What it hands off, not handles]

## Constraints

- Do not modify [out-of-scope files/systems]
- When [situation], [action]

Key principles: state scope explicitly, use imperative language, define handoff conditions, stay well under 30,000 characters.

[!TIP] For detailed principles, anti-patterns, and guidance on what NOT to include, load references/prompt-writing-guide.md.

Creating an Agent Profile: Step-by-Step

Step 1: Plan

1. Define the role and domain (one sentence)
2. List responsibilities and what it does NOT do
3. Choose the surfaces (target) and scope (repository, user, org)
4. Identify required tools, starting read-only

Step 2: Create the File

VS Code:

1. Select the agent harness you intend to use with the Session Target control, then open the Agent Customizations editor: Open Customizations in the Chat view title bar (or the Customizations panel in the Agents window), then Agents
2. Select New Agent (plus icon) next to the Workspace or User group, or run Chat: New Custom Agent from the Command Palette
3. To generate one with AI, describe the agent in the editor's Overview section, or, in a Local harness session, type /create-agent <description> in chat

GitHub.com (cloud agent):

1. Go to github.com/copilot/agents, select the repository (and optionally branch) in the prompt box
2. Click the Copilot icon → Create an agent to open a my-agent.agent.md template in .github/agents
3. For org/enterprise agents, remove the .github/ part of the path so the file lives in the root agents/ directory
4. Rename, configure, commit, and merge into the default branch

Copilot CLI:

1. In interactive mode, enter /agent, then press N to create a new agent
2. Choose Project (.github/agents/) or User (~/.copilot/agents/)
3. Let Copilot generate the profile or fill it in manually, choose tools, then restart the CLI

Manually: create .github/agents/<name>.agent.md. Filename characters: ., -, _, a-z, A-Z, 0-9. Prefer lowercase with hyphens.

Step 3: Write Frontmatter

---
name: api-reviewer
description: Reviews REST API designs for correctness and security. Does not implement code.
tools: ["read", "search"]
---

Step 4: Write the Prompt Body

Follow the template above. Be specific about scope and handoff conditions.

Step 5: Test

1. Select the agent: VS Code agents dropdown, GitHub.com agents panel or issue assignment, or copilot --agent <name> / /agent in the CLI
2. Run representative prompts covering normal use and edge cases
3. Verify scope boundaries and tool restrictions are respected
4. Confirm handoffs and subagent delegation work where used
5. In VS Code, check load errors in the chat customization diagnostics (right-click the Chat view → Diagnostics)

Security Considerations

• Least privilege for tools. Read-only agents cannot accidentally modify files or run commands.
• Review shared agents. Audit tool lists and prompts before committing to a repository.
• Secrets in MCP config. Use ${{ secrets.NAME }} / ${{ vars.NAME }} (configured as Agents secrets/variables). Never hardcode credentials.
• Organization and enterprise agents. They are available to every repo in scope. Review them carefully.
• Added directories (CLI). Agents under a directory added with --add-dir load as trusted configuration.

Reference Files

Official Documentation