agent-creator-copilot
Guide for creating custom agents for GitHub Copilot (cloud agent on GitHub.com, Copilot CLI, VS Code, and other IDEs). Use this when building custom agent profiles (.agent.md files), configuring tools
SKILL.mdskills/agent-creator-copilot/SKILL.md
GitHubCopilot 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 October 2026 against GitHub Copilot CLI v1.0.103. Always verify against the official docs before relying on a property. The canonical references are:
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
| Need | Approach |
|---|---|
| Persistent persona with tool restrictions | Custom agent profile (this skill) |
| One-off reusable task instructions | Prompt file (.prompt.md) |
| Portable domain knowledge with scripts | Agent skill (SKILL.md) |
| Deterministic command at a lifecycle event | Hook |
| Deep VS Code IDE integration, custom UI | VS Code extension |
| Custom tools exposed via protocol | MCP server |
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
| Scope | Location | Surfaces |
|---|---|---|
| Repository / workspace | .github/agents/<name>.agent.md |
All |
| Repository (Claude format) | .claude/agents/<name>.md |
VS Code, Copilot CLI |
| User | ~/.copilot/agents/ |
VS Code, Copilot CLI |
| User (Claude format) | ~/.claude/agents/ |
VS Code |
| Organization | agents/<name>.md in the org's .github or .github-private repo |
GitHub.com, IDEs (VS Code discovers them by default; github.copilot.chat.organizationCustomAgents.enabled set to false turns that off) |
| Enterprise | agents/<name>.md in the .github-private repo of an org designated in enterprise settings |
GitHub.com, IDEs |
| Plugin | <plugin>/agents/ |
Copilot CLI |
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 inreferences/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: falsehides an agent from the picker (subagent/programmatic use only).disable-model-invocation: truestops other agents (VS Code) or the cloud agent (GitHub.com) from auto-selecting it. In VS Code, explicitly listing the agent in a coordinator'sagentsoverrides this.- In Copilot CLI, the main agent can run any custom agent as a subagent by inference. Add
include-custom-instructions: trueif the subagent should readAGENTS.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
- Define the role and domain (one sentence)
- List responsibilities and what it does NOT do
- Choose the surfaces (
target) and scope (repository, user, org) - Identify required tools, starting read-only
Step 2: Create the File
VS Code:
- 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
- Select New Agent (plus icon) next to the Workspace or User group, or run Chat: New Custom Agent from the Command Palette
- 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):
- Go to github.com/copilot/agents, select the repository (and optionally branch) in the prompt box
- Click the Copilot icon → Create an agent to open a
my-agent.agent.mdtemplate in.github/agents - For org/enterprise agents, remove the
.github/part of the path so the file lives in the rootagents/directory - Rename, configure, commit, and merge into the default branch
Copilot CLI:
- In interactive mode, enter
/agent, then pressNto create a new agent - Choose Project (
.github/agents/) or User (~/.copilot/agents/) - 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
- Select the agent: VS Code agents dropdown, GitHub.com agents panel or issue assignment, or
copilot --agent <name>//agentin the CLI - Run representative prompts covering normal use and edge cases
- Verify scope boundaries and tool restrictions are respected
- Confirm handoffs and subagent delegation work where used
- 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-dirload as trusted configuration.
Reference Files
| File | When to Load |
|---|---|
references/frontmatter-reference.md |
Full property tables, surface compatibility, model naming, handoffs, hooks, MCP config, CLI-only fields, Claude format |
references/tools-reference.md |
Tool aliases, VS Code tool names, deprecated tool sets, MCP namespacing, out-of-the-box MCP servers |
references/prompt-writing-guide.md |
Detailed prompt principles, anti-patterns, output format guidance |
references/workspace-agent-example.agent.md |
VS Code workspace agent with handoffs and model fallback |
references/user-profile-agent-example.agent.md |
Minimal personal agent |
references/cloud-agent-with-mcp-example.agent.md |
GitHub.com cloud agent with MCP config and metadata |