Skip to content

CowboyLogic/ai-dev / skills/agent-creator-copilot

agent-creator-copilot

Verified

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, models, handoffs, subagents, hooks, or MCP server integrations for Copilot.

# Copilot Agent Creator

A skill for creating custom agents for GitHub Copilot: Copilot cloud agent on GitHub.com, GitHub Copilot CLI, VS Code, and other supported IDEs.

## Associated Copilot CLI version

| | |
|---|---|
| GitHub Copilot CLI | **v1.0.105** (released 2026-10-28, the latest stable release as of 2026-11-01) |
| References last verified | 2026-11-01 |
| Sources | docs.github.com Copilot custom-agent and CLI documentation, the supported-models page, and VS Code documentation at code.visualstudio.com as published through 2026-10-30 (see the reference files for URLs) |

The model roster and retirement dates change often; check the supported-models page before
pinning a model.

## Overview

Custom agents are specialized Copilot configurations defined in `.agent.md` Markdown files called **agent profiles**. They encode a domain role, behavioral instructions, tool access, and optionally a model into a reusable, shareable file, without requiring any extension development.

This skill covers:

- Agent profile format and supported frontmatter properties, with a per-surface compatibility table
- Where to store agent files (repository, user, organization, enterprise, CLI plugins)
- Tools configuration: cross-platform aliases, VS Code tool names (user-defined tool sets are deprecated), MCP namespacing
- Model selection and current model names, including retired models to avoid
- Handoffs and subagents in VS Code, and agent-scoped hooks in VS Code (Local harness) and Copilot CLI
- CLI-only fields (`models`, `modelPolicy`, `reasoningEffort`, `include-custom-instructions`)
- MCP server configuration and secrets for the cloud agent
- Writing effective agent prompts and descriptions
- The Claude agent format for cross-tool compatibility

## Quick Start

1. In VS Code, select **Open Customizations** in the Chat view title bar → **Agents**, then select **New Agent** (plus icon) next to the **Workspace** group
2. Enter a filename. A `.agent.md` file is created in `.github/agents/`
3. Add a `description` and write the prompt body
4. Select your agent in the agents dropdown and test it

Alternatives: run `/agent` and press **N** in Copilot CLI, or use **Create an agent** at [github.com/copilot/agents](https://github.com/copilot/agents).

## Key Concepts

### Agent Profiles vs. Other Customizations

| Use | When |
|---|---|
| **Agent profile** | Persistent persona, tool restrictions, handoffs between roles |
| **Prompt file** | One-off reusable instructions |
| **Skill (SKILL.md)** | Portable domain knowledge loaded when relevant |
| **Hook** | Deterministic command at a lifecycle event |
| **VS Code extension** | Deep IDE integration, custom UI |
| **MCP server** | Custom tools exposed via Model Context Protocol |

### Scope Levels

| Scope | Location |
|---|---|
| Repository | `.github/agents/<name>.agent.md` |
| User | `~/.copilot/agents/<name>.agent.md` (VS Code, CLI) |
| Organization | `agents/<name>.md` in the org's `.github` or `.github-private` repo |
| Enterprise | `agents/<name>.md` in the `.github-private` repo of an org designated in enterprise settings |
| Claude compat | `.claude/agents/<name>.md` (VS Code, CLI), `~/.claude/agents/` (VS Code) |

## Example Files

- [workspace-agent-example.agent.md](references/workspace-agent-example.agent.md): VS Code workspace agent with a model fallback list, `argument-hint`, and handoffs
- [user-profile-agent-example.agent.md](references/user-profile-agent-example.agent.md): minimal personal agent. Its `model` uses the VS Code display name; the CLI expects IDs such as `gpt-5.6-luna`
- [cloud-agent-with-mcp-example.agent.md](references/cloud-agent-with-mcp-example.agent.md): GitHub.com cloud agent with inline MCP server config, a `COPILOT_MCP_` secret, and metadata

## Official Documentation

| Resource | URL |
|---|---|
| About custom agents | <https://docs.github.com/en/copilot/concepts/customizations/custom-agents> |
| Create custom agents (cloud agent) | <https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-cloud-agent/create-custom-agents> |
| Configuration reference | <https://docs.github.com/en/copilot/reference/custom-agents-configuration> |
| Custom agents for Copilot CLI | <https://docs.github.com/en/copilot/how-tos/copilot-cli/customize-copilot/create-custom-agents-for-cli> |
| Custom agents in VS Code | <https://code.visualstudio.com/docs/agent-customization/custom-agents> |
| Custom agent file reference (VS Code) | <https://code.visualstudio.com/docs/agents/reference/custom-agent-file-reference> |
| Migrate Copilot customizations in VS Code | <https://code.visualstudio.com/docs/agent-customization/migrate-customizations> |
| Supported AI models | <https://docs.github.com/en/copilot/reference/ai-models/supported-models> |
| Awesome Copilot agents | <https://github.com/github/awesome-copilot/tree/main/agents> |
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall