Create Custom Agent

This skill guides you through creating a custom GitHub Copilot agent — an @-invokable chat participant that extends Copilot with domain-specific expertise. Custom agents are distinct from Agent Skills: skills provide reusable instructions loaded on demand, while agents own the full conversational interaction and can orchestrate tools, call APIs, and maintain their own prompt strategies.

When Not to Use

• Adding reusable, invokable workflows — use Agent Skills (.agents/skills/) instead
• Adding background coding guidelines — use file-based instructions (.github/instructions/) instead
• Adding project-wide context for Copilot — use .github/copilot-instructions.md instead
• Creating reusable prompts — use .prompt.md instead

Workflow

For an existing proposal, audit the full definition rather than just its tools: the description must identify natural requests that should discover it, the body must add domain knowledge beyond root instructions, and the paired eval must isolate its contribution. Compare every tool and behavior to the user's intended authority. A command-free reviewer must not gain command execution or publication through a wildcard tool, handoff, or otherwise read-only workflow.

Step 1: Choose the agent type

If the agent only needs a scoped system prompt and doesn't require custom code, start with a declarative agent.

Step 2: Create a declarative agent (prompt file)

Declarative agents are Markdown files in .github/agents/. VS Code and GitHub Copilot discover them automatically.

.github/agents/
└── <agent-name>.md        # Agent definition

Template:

---
name: my-agent
description: A short description of what this agent does and when to use it.
---

# <Agent Title>

You are an expert in <domain>. Your job is to:
- <behavior 1>
- <behavior 2>

## Guidelines

- <guideline 1>
- <guideline 2>

## Workflow

1. <step 1>
2. <step 2>

## Constraints

- <constraint 1>
- <constraint 2>

Supported frontmatter fields:

Tips for instructions:

• Use Markdown links to reference other files
• Reference tools with #tool:<tool-name> syntax
• Be specific about agent behavior and constraints

Step 3: Configure tools

Specify which tools the agent can use:

tools:
  - search              # Built-in tool
  - fetch               # Built-in tool
  - codebase            # Tool set
  - myServer/*          # All tools from MCP server

Common tool patterns:

• Read-only agents: ['search', 'fetch', 'codebase']
• Full editing agents: ['*'] or specific editing tools
• Specialized agents: Cherry-pick specific tools

Step 4: Add handoffs (optional, VS Code only)

Configure transitions to other agents:

handoffs:
  - label: Start Implementation
    agent: implementation
    prompt: Implement the plan outlined above.
    send: false
    model: GPT-5.2 (copilot)

Handoff fields:

• label: Button text displayed to user
• agent: Target agent identifier
• prompt: Pre-filled prompt for target agent
• send: Auto-submit prompt (default: false)
• model: Optional model override for handoff

Step 5: Create an extension-based chat participant (VS Code only)

For full control, implement a VS Code extension with a chat participant:

1. Define the participant in package.json:

"contributes": {
    "chatParticipants": [
        {
            "id": "my-extension.my-agent",
            "name": "my-agent",
            "fullName": "My Agent",
            "description": "Short description shown in chat input",
            "isSticky": false,
            "commands": [
                {
                    "name": "explain",
                    "description": "Explain the selected code"
                }
            ]
        }
    ]
}

2. Register and implement the request handler in extension.ts:

export function activate(context: vscode.ExtensionContext) {
    const agent = vscode.chat.createChatParticipant('my-extension.my-agent', handler);
    agent.iconPath = vscode.Uri.joinPath(context.extensionUri, 'icon.png');
}

const handler: vscode.ChatRequestHandler = async (
    request: vscode.ChatRequest,
    context: vscode.ChatContext,
    stream: vscode.ChatResponseStream,
    token: vscode.CancellationToken
) => {
    const model = request.model;
    const messages = [
        vscode.LanguageModelChatMessage.User(request.prompt)
    ];
    const response = await model.sendRequest(messages, {}, token);
    for await (const fragment of response.text) {
        stream.markdown(fragment);
    }
};

3. Declare the extension dependency in package.json:

"extensionDependencies": ["github.copilot-chat"]

4. Add tool calling (optional)

Agents can invoke language model tools registered by other extensions:

const tools = vscode.lm.tools.filter(tool => tool.tags.includes('my-domain'));
const result = await chatUtils.sendChatParticipantRequest(request, context, {
    prompt: 'You are an expert in <domain>.',
    tools,
    responseStreamOptions: { stream, references: true, responseText: true }
}, token);
return await result.result;

Step 6: Create a GitHub App (Copilot Extension) for cross-surface availability (optional)

If the agent should be available on GitHub.com, Visual Studio, JetBrains, and VS Code simultaneously, implement a GitHub App that acts as a Copilot Extension. The app registers a webhook endpoint, receives chat requests, and streams responses back.

Key considerations:

• The GitHub App must be installed on the user's account or organization
• Responses are streamed via Server-Sent Events (SSE)
• Use the GitHub Copilot Extensions documentation for the full integration guide
• For VS Code-specific features (editor access, file trees, command buttons), prefer an extension-based participant instead

Step 7: Author the harness evaluation

Create eng/harness-evaluation/agents/<agent-id>/eval.yaml and follow eng/harness-evaluation/README.md.

• Declare only the agent file in the eval's root agent_environment.files; the experiment removes it from the control.
• Use realistic stimuli that exercise behavior distinctive to the agent without stating the expected diagnosis or implementation in the prompt.
• Combine deterministic output checks, a focused semantic rubric, bounded resources, token grading, and a committed scoring threshold.
• Keep the eval name and directory-derived component ID identical to the agent ID.

Step 8: Validate

After creating or modifying an agent, verify:

• name is lowercase, uses hyphens (no spaces), and is unique
• description clearly describes what the agent does and when to invoke it
• Frontmatter YAML is valid (no syntax errors)
• Declarative agent file is in .github/agents/
• Tools list contains only available tools
• Extension-based agent: participant ID matches in package.json and createChatParticipant call
• Agent does not duplicate functionality of built-in agents (@workspace, @vscode, @terminal)
• Handoff agent names match existing agents
• Agent instructions don't include secrets, tokens, or internal URLs
• The paired harness eval targets only this agent and is meant to meaningfully distinguish treatment from control

Common Pitfalls

References

• VS Code Chat Participant API
• VS Code AI Extensibility Overview
• VS Code Extension Samples – chat-sample
• GitHub Copilot Extensions documentation
• GitHub Copilot Custom agents configuration
• Agent Skills Specification
• Related repository skills: make-skill and make-instructions