Forem: seiwan maikuma

A Deep Dive into GitHub Copilot Agent Mode’s Prompt Structure

seiwan maikuma — Sat, 27 Dec 2025 14:15:18 +0000

Introduction

GitHub Copilot is not “just” a code completion tool—it behaves like an AI coder powered by layered prompt engineering. When you type a request, Copilot typically sends a multi-layer prompt to the model behind the scenes.

In this article, we closely analyze the prompt structure GitHub Copilot appears to use, and extract the underlying design philosophy and practical prompt-engineering best practices. This is aimed at engineers who want to use AI tools more effectively and developers interested in learning prompt engineering through real-world systems.

Test environment & methodology

This article is based on observation and analysis under the following setup:

Verification date: Dec 27, 2025
VS Code version: 1.107
Method: Inspecting logs via Chat Debug view (official VS Code debugging feature)

Chat Debug view is an official mechanism to inspect Copilot Chat’s internal behavior. Using it, we observed the structure of prompts actually passed into the model.

:::message alert
Because this write-up is based on log interpretation, it may contain mistakes. Also, Copilot’s internal prompt structure can change with updates.
:::

Why should we care about prompt structure?

Understanding Copilot’s prompt layers helps you:

Give better instructions: You learn what context is (and isn’t) already provided.
Learn best practices: You can study a production-grade prompt design created by Microsoft/GitHub.
Explain Copilot’s behavior: “Why did it do that?” becomes easier to answer.
Design your own agent: The architectural ideas transfer well to custom AI agents.

The 3-layer prompt structure Copilot receives

Copilot’s prompt often looks like a layered system:


Layer 1: System prompt
↓ (universal rules for “AI coder” behavior)
Layer 2: Workspace information
↓ (environment-specific context)
Layer 3: User request + extra context
↓ (the actual task)
Model response

Roles of each layer

Layer 1 (System prompt)

Universal, environment-independent instructions: tool strategy, workflow, communication style, safety rules, output format.
Layer 2 (Workspace info)

Dynamic environment context: OS, repository/workspace structure, current file, etc.
Layer 3 (User request)

Your input, plus additional context such as date, reminders, attachments, selected text, screenshots, and so on.

This separation keeps the “rules” stable while allowing environment-specific details to vary per session.

Layer 1: System prompt — the “AI coder” design philosophy

The system prompt is Copilot’s brain. It defines how the model should behave.

Purpose of the system prompt

Typical elements include:

Identity: “You are GitHub Copilot,” sometimes including the model family/version.
Policy compliance: content policy, copyright constraints, refusal behavior.
Baseline stance: concise, objective answers; strict compliance with user requirements.

Tool usage strategy

Copilot has multiple tools; the system prompt usually instructs when to use what.

Context-gathering tools

read_file

Read large ranges at once (e.g., up to ~2000 lines) to reduce repeated calls and keep context coherent.
semantic_search

Use when you don’t know where a function/file is; search by meaning, not just keywords.
grep_search

Use for quick discovery within files; often faster than reading everything.
fetch_webpage

If a URL is included in context, fetch it; sometimes also follow related links recursively.

File-editing strategy

Editing is expensive and error-prone, so the system prompt often enforces:

Read before you edit: ensure you understand the file and identify the exact location.
Include enough context: e.g., “include ±3 lines around the edit target” so patches apply reliably.
Small, testable increments: make changes in steps that can be validated.
Avoid error loops: if you fail repeatedly on the same file, switch approaches.

The 8-step workflow design

A core part of “agent mode” behavior is a structured workflow—an explicit thinking/working process:

Step 1: Deeply understand the problem

What is the expected behavior?
What are the edge cases?
What pitfalls are likely?
Where does this fit in the overall codebase?

The key idea: don’t write code immediately—first understand what must be true.

Step 2: Investigate the codebase

Explore related files and directories
Search for key functions/classes/variables
Identify the root cause
Continuously update your understanding as you learn more

Even if context is missing, the agent is pushed to use tools to find what it needs.

Step 3: Produce a detailed plan

Make a concrete, verifiable plan
Create a TODO list (often via a dedicated tool)
Update progress after each step
Important: proceed to the next step without repeatedly asking the user, if you can act safely

This is a major “agent” characteristic: autonomous forward motion.

Step 4: Implement changes

Read relevant files first (large chunks)
Make small, testable changes
Create .env automatically if environment variables are required
Retry if patch application fails

Step 5: Debug

Use error collection tools to inspect problems
Fix the cause, not just the symptom
Temporary debug code is allowed (logs/prints/tests) to validate hypotheses

Step 6: Test frequently

Run tests after each change
Ensure both visible and hidden tests pass
When tests fail, find the true root cause

Step 7: Iterate until fixed

Continue until all tests pass
If stuck looping in the same file multiple times, change strategy

Step 8: Comprehensive verification & reflection

Re-check the original intent
Add extra tests if needed
Update TODO list: done / skipped / blocked items must be explicit

This shows Copilot is designed to behave like a systematic problem-solver, not a chat bot.

Communication guidelines

System prompts usually define communication rules too:

Tone: warm, professional, approachable
Brevity: keep it short and structured
Critical thinking: don’t blindly obey user corrections—think first
Humor: light wit is allowed when appropriate

Output formatting requirements

To optimize readability in the editor UI:

Use Markdown
Wrap symbols in backticks: MyClass, handleClick()
Use linkable file paths (workspace-relative) when possible
Use KaTeX for math when relevant

Layer 2: Workspace information — environment-specific optimization

This layer provides context unique to the user’s environment.

Typical environment information

OS info

Example:

The user's current OS is: Windows

This influences:

command syntax (PowerShell vs bash)
path separators (\ vs /)
OS-specific instructions

Workspace structure

Example:

I am working in a workspace with the following folders:
- c:\CodeStudy\Prompts

I am working in a workspace that has the following structure:
README.md
ai_coder/
  github_copilot/
    agent/
      basic.general.md
...

This helps the model:

decide which files matter
construct correct absolute paths for tools
quickly grasp project layout

Large repos may provide abbreviated trees, prompting the agent to fetch more context with tools.

Why Layer 2 matters

higher accuracy via environment awareness
fewer tool errors due to correct path handling
faster project comprehension
more stable parsing when the info is structured (e.g., XML-like tags)

Layer 3: User request — context amplification

This is your request, plus extra metadata attached by the system.

Common additions

Date context

<context>
The current date is December 27, 2025.
</context>

Useful for time-sensitive tasks (log analysis, deadlines, version recency).

Editor context

<editorContext>
The user's current file is at: c:\...\somefile.md
</editorContext>

This makes “this file” understandable and keeps the working set coherent.

Attachments

Selected text, screenshots, and attached files may be included under something like <attachments>.

Reminder instructions (agent behavior reinforcement)

A key feature is explicit instruction like:

<reminderInstructions>
You are an agent - you must keep going until the user's query is completely resolved,
before ending your turn and yielding back to the user. ONLY terminate your turn when
you are sure that the problem is solved, or you absolutely cannot continue.

You take action when possible - the user is expecting YOU to take action and go to
work for them. Don't ask unnecessary questions about the details if you can simply
DO something useful instead.
</reminderInstructions>

The philosophy:

Autonomy: keep working until done; don’t freeze on uncertainty
Action-first: prefer doing useful work over asking extra questions

Key design principles & best practices

From this structure, we can extract reusable prompt engineering lessons.

1) Hierarchical prompt design

Separate:

stable universal rules (system)
dynamic environment context (workspace)
per-request task details (user request)

This improves maintainability and reuse.

2) Structured workflow

Explicitly encode the agent’s process:
understand → investigate → plan → implement → debug → test → iterate → verify

3) Clear tool guidelines

Don’t just provide tools—define when and how to use them.

4) Autonomy + action orientation

Give the agent permission and responsibility to proceed, with guardrails.

5) Context before action

Quality of output correlates strongly with quality/amount of context.

6) Structured tags (XML/JSON-like)

Segment complex info clearly to reduce misinterpretation.

7) Error-handling strategy

Predefine what to do when stuck: retry, then switch approach after repeated failures.

8) Standardized output format

Consistency improves user experience and reduces confusion.

Applying this to prompt engineering

You can reuse the same architecture in your own systems.

Example: designing your own AI agent prompt

# System prompt (stable rules)
You are a professional data analyst.
Follow this workflow:
1. Understand the data
2. Create an analysis plan
3. Execute the analysis in small steps
...

# Environment info (dynamic)
<environment>
Data source: PostgreSQL
Available tools: pandas, matplotlib
</environment>

# User request (per task)
<task>
Analyze sales trends and summarize key insights.
</task>

<reminder>
Keep going until the analysis is complete.
</reminder>

How to write effective requests to Copilot

✅ Better:

Fix the error in the current file.
Also check related tests and ensure all tests pass.

This gives:

a clear goal
autonomy for the agent
alignment with the workflow (investigate → fix → test)

❌ Worse:

Tell me if there is an error.

This:

requests information only
doesn’t trigger action
leaves next steps ambiguous

General prompt principles learned here

clarity
structure
sufficient context
controlled autonomy
verifiable success criteria
incremental steps
flexible error handling
consistency

Conclusion

By analyzing Copilot’s layered prompt structure, we can see it behaves like a systematic problem-solving agent.

What the prompt structure boils down to

Layer 1: universal agent rules (tools + 8-step workflow + format + policy)
Layer 2: environment context (OS + workspace tree + current file)
Layer 3: your request plus metadata (date + attachments + “keep going” reminder)

Practical takeaways

Layer your prompts for maintainability
Encode workflows explicitly
Specify tool usage rules
Give autonomy with guardrails
Standardize output

Copilot’s architecture is a strong reference implementation for anyone building AI agents or designing prompts for complex engineering tasks.

References

Official docs

Internals / reverse engineering

The Complete Guide to Meta-Prompting: The Technique of Having AI Write Your Prompts

seiwan maikuma — Sun, 14 Dec 2025 16:10:30 +0000

TL;DR (Conclusion)

What a meta-prompt is: A higher-order prompting technique that makes AI generate and improve prompts
Main benefit: You can get structured, clarified prompts at low cost
Practicality: Effective enough that Anthropic and OpenAI provide official tools
Advanced results: Stanford/OpenAI research reports a 17.1% improvement over standard prompting

1. What Is a Meta-Prompt?

A meta-prompt is a higher-level prompt used to create the prompt you will give to AI.

If a normal prompt is “instructions to AI,” a meta-prompt is “instructions for creating instructions to AI.”

Normal Prompt vs. Meta-Prompt

The Two Components of a Meta-Prompt

A meta-prompt usually consists of two parts:

Component	Role	Example
Prompt improvement instructions	Tell the model how to improve the normal prompt	“Improve the following prompt so it includes more specific and clear instructions.”
Normal prompt	Convey the user’s real goal	“Propose five innovative business ideas.”

2. Why Meta-Prompting Works

2.1 The “Formatter” Effect

AI is good at presenting information in consistent formats. Using a meta-prompt tends to produce a more structured prompt than one written directly by a human.

2.2 The Clarification Effect

Meta-prompts push the model to avoid vague instructions and replace them with specific, concrete ones. In the process, the user can also notice ambiguities that were hiding in their own prompt or task.

2.3 Low Cost

The only real overhead is writing the “prompt improvement instructions.” In most cases, very simple instructions are enough—much cheaper than writing a clear, structured prompt from scratch.

2.4 Simplifying the Normal Prompt

Because the meta-prompt handles structure and clarity, the normal prompt can focus on the essential content.

2.5 Better Accuracy

Accuracy improvements come from two angles:

Clear instructions: As the meta-prompt forces clarity, the model can understand the user’s intent more precisely.
The model’s reasoning gets embedded in the prompt: During improvement, the prompt often picks up optimal steps and necessary context.

3. Understanding Meta-Prompting as a Function

If you view meta-prompting through the lens of functional programming, the essence becomes clearer.

3.1 Basic Model

// Type definitions
type Prompt = string;
type Response = string;

// Normal AI call
const ai: (prompt: Prompt) => Response;

// Prompt improvement function
type PromptImprover = (prompt: Prompt) => Prompt;

// How meta-prompting works
function metaPrompt(
  improveInstruction: string,  // prompt improvement instructions
  userPrompt: Prompt           // normal prompt
): Response {
  // Step 1: Improve the normal prompt based on the improvement instructions
  const improvedPrompt: Prompt = ai(improveInstruction + userPrompt);

  // Step 2: Call the AI using the improved prompt
  const finalResponse: Response = ai(improvedPrompt);

  return finalResponse;
}

3.2 Understanding It as Function Composition

// Treat prompt improvers as composable functions
const improve1: PromptImprover = (p) => ai(`Please structure this: ${p}`);
const improve2: PromptImprover = (p) => ai(`Please add concrete examples: ${p}`);

// Function composition (multi-stage meta-prompting)
const compose = <T>(f: (x: T) => T, g: (x: T) => T) => (x: T) => g(f(x));
const improveAll = compose(improve1, improve2);

// Run it
const improvedPrompt = improveAll(userPrompt);
const response = ai(improvedPrompt);

4. Practical Meta-Prompting Methods

4.1 Anthropic’s Prompt Generator

Anthropic officially provides a Prompt Generator.

Key features:

Automatically incorporates Chain-of-Thought (reasoning steps)
Separates data and instructions using XML tags
Supports variables with Handlebars notation

The prompt generator is particularly useful as a tool for solving the "blank page problem" to give you a jumping-off point for further testing and iteration.
— Anthropic Docs

4.2 Stanford/OpenAI Meta-Prompting

Meta-Prompting, published in January 2024 as a joint Stanford/OpenAI research project, proposes a more advanced approach.

Architecture:

Results (with a Python interpreter):

Baseline	Improvement
Standard prompt	+17.1%
Expert (dynamic) prompt	+17.3%
Multi-persona prompt	+15.2%

These numbers are averaged across tasks like Game of 24, Checkmate-in-One, Python Programming Puzzles, etc.

4.3 DSPy / TextGrad

As more technical approaches, these frameworks are drawing attention:

DSPy: Treats LLMs as modular components and optimizes prompts programmatically
TextGrad: Uses natural-language feedback as “text gradients” to iteratively improve prompts

5. Meta-Meta-Prompts: An Advanced Concept

5.1 Introducing the Idea

If you extend meta-prompting, you get the concept of a meta-meta-prompt: a “prompt for generating meta-prompts.”

5.2 Two Patterns

Pattern A: Improve the normal prompt in multiple stages

Mathematical expression:

const fn1: PromptImprover = /* Instruction A */;
const fn2: PromptImprover = /* Instruction B */;

// Function composition
const improvedPrompt = fn2(fn1(userPrompt));
const response = ai(improvedPrompt);

Essence: Simple function composition—iterative prompt improvement.

Pattern B: Generate the prompt improvement instructions themselves

Mathematical expression:

// Clearly define the type hierarchy
type Prompt = string;

// Level 1: A function that improves a prompt
type PromptImprover = (p: Prompt) => Prompt;

// Level 2: A function that improves a prompt-improver (meta-meta-prompt)
type ImproverImprover = (f: PromptImprover) => PromptImprover;

// Level 3: In theory, even higher levels can exist
type MetaImproverImprover = (g: ImproverImprover) => ImproverImprover;

// Example implementation
const baseImprover: PromptImprover = (p) => 
  ai(`Please structure this: ${p}`);

const improverImprover: ImproverImprover = (f) => {
  // Take an existing improver and return an enhanced improver
  return (p) => {
    const firstPass = f(p);
    return ai(`Please refine this improved result even further: ${firstPass}`);
  };
};

// Apply the meta-meta-prompt
const enhancedImprover = improverImprover(baseImprover);
const improvedPrompt = enhancedImprover(userPrompt);
const response = ai(improvedPrompt);

Essence: A hierarchy of higher-order functions. Each level is defined as “a function that improves functions one level below.”

Level 0: Prompt                                 (value)
Level 1: Prompt → Prompt                         (PromptImprover)
Level 2: (Prompt → Prompt) → (Prompt → Prompt)   (ImproverImprover)
Level 3: ...                                     (higher levels)

5.3 Practicality

Pattern	Practicality	When to use
Pattern A	High	Complex tasks, tasks involving information gathering (e.g., “Plan mode” for AI coding assistance)
Pattern B	Medium	Specialized domains where it’s hard to template improvement instructions

6. Implementation Examples and Tools

6.1 Anthropic Prompt Generator (Official)

You can use it directly from Anthropic’s Developer Console.

You can also review the architecture in their Google Colab notebook.

6.2 OpenAI System Instruction Generator

Available in OpenAI’s Playground (excluding the o1 model).

6.3 A Simple Implementation Example

import anthropic

def meta_prompt(user_task: str) -> str:
    """
    Generate a task prompt using meta-prompting.
    """
    client = anthropic.Anthropic()

    meta_instruction = """
    Convert the following task description into a high-quality prompt.

    The prompt should include:
    1. A clear role definition
    2. A concrete task description
    3. The expected output format
    4. Constraints (if any)

    Task description:
    """

    # Step 1: Generate the prompt
    response = client.messages.create(
        model="claude-sonnet-4-20250514",  # Check the official docs for the latest model name
        max_tokens=1024,
        messages=[
            {"role": "user", "content": meta_instruction + user_task}
        ]
    )

    return response.content[0].text

📋 Disclaimer

Important: This article was created through dialogue with Claude, so it may contain mistakes.

7. Summary

The Value of Meta-Prompting

Efficiency: Greatly reduces the time spent manually optimizing prompts
Quality: Structured, clarified prompts improve response accuracy
Scalability: Templates make it reusable across many tasks

Recommended Approach

Reference Resources

:::message alert
Note: Meta-prompting isn’t magic. For simple tasks, a normal prompt is often enough, and too much abstraction can backfire. Choose the right approach based on task complexity.
:::

Deep Dive into the Latest GitHub Copilot Updates

seiwan maikuma — Thu, 11 Dec 2025 14:30:54 +0000

In VS Code November 2025 Insiders (v1.107), the GitHub Copilot agent features received a major upgrade.

This article walks through three particularly interesting experimental features in detail.

Reference: VS Code Release Notes v1.107

1. Running Agents as Subagents (Experimental)

What is a Subagent?

A subagent (Context-Isolated Subagent) is a context-isolated autonomous agent that can be invoked from within a main chat session.

It has its own context window independent from the main session and is well suited for complex multi-step tasks such as research and analysis.

Reference: Chat Sessions - Context-isolated subagents

┌────────────────────────────────────────────────────┐
│ Main Chat Session                                  │
│ ┌────────────────────────────────────────────────┐ │
│ │ User: Research best practices for auth,        │ │
│ │       then create an implementation plan       │ │
│ └────────────────────────────────────────────────┘ │
│                     ↓                              │
│ ┌────────────────────────────────────────────────┐ │
│ │ Subagent launched                              │ │
│ │ - Independent context window                   │ │
│ │ - Runs research via read-only tools            │ │
│ │ - Returns only the final result to main chat   │ │
│ └────────────────────────────────────────────────┘ │
│                     ↓                              │
│ ┌────────────────────────────────────────────────┐ │
│ │ Continue planning in the main session          │ │
│ │ (using the subagent’s research results)        │ │
│ └────────────────────────────────────────────────┘ │
└────────────────────────────────────────────────────┘

Characteristics

Property	Details
Context isolation	Does not consume the main session’s context
Autonomous execution	Runs to completion without user feedback
Result handoff	Only the final result is returned to the main session
Tool access	Inherits the same tools as the main session by default Can specify its own toolset via custom agents
Model	Uses the same AI model as the main session by default Can use its own model via custom agents

Extension via experimental feature:
When the chat.customAgentInSubagent.enabled setting is enabled, you can specify a different custom agent for a subagent.
Because a custom agent can define its own tools: and model: properties, you can assign a specialized toolset and optimal AI model per subagent. (Verified in practice by the author.)

Reference links:

Official docs: Context-isolated subagents

GitHub Issue #275855: Request for model selection per subagent – Community request to “explicitly specify different models for each subagent”

Model selection in custom agents

How to Use

Enable the runSubagent tool in the Tool Picker.
In a prompt, explicitly instruct Copilot to run a subagent.

<!-- Example 1: Research task -->
Use a subagent to research authentication methods for web applications.
Summarize your findings.

<!-- Example 2: Explicitly referencing #runSubagent -->
Use #runSubagent to comprehensively research the user’s task using read-only tools,
and once you reach 80% confidence, return the context needed for planning.

Combining with Custom Agents (Experimental)

When chat.customAgentInSubagent.enabled is enabled, you can have a subagent use a different custom agent.

<!-- Run the "research" agent as a subagent -->
Run the research agent as a subagent
and investigate the best authentication methods for this project.

<!-- Use the "plan" agent as a subagent to create a plan and save it to a file -->
Use the plan agent as a subagent to create an implementation plan for "myfeature"
and save it to plans/myfeature.plan.md.

Subagents vs Normal Agents

Aspect	Subagent	Normal agent
Execution host	Inside the main session	Separate session
Context	Isolated (efficient)	Shared or fully independent
User feedback	None (autonomous)	Can request feedback as needed
Result sharing	Only returns the final result	Full conversation history available
Best suited for	Research, analysis, subtasks	Mainline development tasks

Why Subagents Matter: Solving the “Too Many Tools” Problem

More Tools ≠ Smarter Agents

Research by the GitHub Copilot team shows that giving an agent too many tools can actually hurt performance.

Reference: How we're making GitHub Copilot smarter with fewer tools - GitHub Blog

VS Code’s GitHub Copilot Chat can access hundreds of tools via MCP.
However, as the number of tools grows, the following issues appear:

Problem	Details
Response latency	Tool selection reasoning becomes slower, adding 400ms+ on average
Worse performance	2–5% lower success rate on the SWE-Lancer benchmark
Wrong tool usage	Ignores explicit instructions or calls unnecessary tools
API limit overrun	Some models can exceed tool-related limits when too many tools exist

You may have seen a spinner like this in VS Code:

🔄 Optimizing tool selection...

This appears while the model is trying to reason over a huge tool set.

GitHub’s Fix: Reduce the Tool Set

(These are the states at the time of the GitHub blog above. With this VS Code update, additional changes have been made.)

The GitHub team reduced the default 40 built-in tools down to 13 core tools.
The remaining tools are grouped into “virtual tool groups” and expanded only when needed.

Core tool set (always available): 13 tools
├── Repository structure analysis
├── File read/write
├── Context search
└── Terminal operations

Virtual tool groups (expanded on demand):
├── Jupyter Notebook Tools
├── Web Interaction Tools
├── VS Code Workspace Tools
└── Testing Tools

Results:

TTFT (Time To First Token): ~190ms faster on average
TTLT (Time To Last Token): ~400ms faster on average

A New Approach with Subagents

With subagents, we now get a new architecture to tackle the too-many-tools problem.

Old Approach (Single Agent + Many Tools)

┌─────────────────────────────────────────┐
│ Main Agent                              │
│ ┌─────────────────────────────────────┐ │
│ │ Tools: 40+                         │ │
│ │ - File operations                  │ │
│ │ - Git commands                     │ │
│ │ - Web search                       │ │
│ │ - Databases                        │ │
│ │ - Test running                     │ │
│ │ - ... many more                    │ │
│ └─────────────────────────────────────┘ │
│ → Tool selection takes time              │
│ → Likely to pick the wrong tool          │
└─────────────────────────────────────────┘

New Approach (Orchestrator + Specialized Subagents)

┌─────────────────────────────────────────────────────┐
│ Main Agent (Orchestrator)                          │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Tools: runSubagent only                        │ │
│ │ Model: Claude Sonnet 4.5 (copilot)             │ │
│ │        (for advanced reasoning)                │ │
│ └─────────────────────────────────────────────────┘ │
│                        ↓                            │
│    ┌───────────┬───────────┬───────────┬─────────┐ │
│    ↓           ↓           ↓           ↓         │ │
│ ┌──────┐  ┌──────┐  ┌──────┐  ┌──────┐          │ │
│ │Research││Impl.  ││Test   ││Git    │          │ │
│ │Agent   ││Agent  ││Agent  ││Agent  │          │ │
│ ├──────┤  ├──────┤  ├──────┤  ├──────┤          │ │
│ │Web   │ │File   │ │Test   │ │Git   │          │ │
│ │search│ │editing│ │running│ │ops   │          │ │
│ ├──────┤  ├──────┤  ├──────┤  ├──────┤          │ │
│ │Sonnet│ │Sonnet │ │Haiku  │ │Haiku │          │ │
│ │4.5   │ │4.5    │ │4.5    │ │4.5   │          │ │
│ └──────┘  └──────┘  └──────┘  └──────┘          │ │
│                                                     │
│ → Each agent has only the minimum tools it needs     │
│ → Tool calls are more accurate                       │
│ → The most suitable model can be chosen per task     │
│   (e.g. Sonnet for complex reasoning, Haiku for      │
│    simple repetitive work)                           │
└─────────────────────────────────────────────────────┘

Concrete Implementation Example

<!-- Custom agent: research-agent.agent.md -->
---
name: research-agent
description: A research agent specializing in web search and information analysis
tools:
  - web_search
  - web_fetch
model: Claude Sonnet 4.5 (copilot)  # Needs strong analytical ability
---

# Research Agent

You are an expert in information research and analysis.
Use web search extensively to conduct comprehensive research on technical topics.
...

<!-- Custom agent: test-agent.agent.md -->
---
name: test-agent
description: An agent specialized in generating and running tests
tools:
  - codebase
  - runTerminal
model: Claude Haiku 4.5 (copilot)  # Lightweight model is sufficient and faster for routine tasks
---

# Test Agent

You are a test automation expert.
Analyze the existing codebase and generate appropriate unit tests.
...

<!-- Custom agent: orchestrator.agent.md -->
---
name: orchestrator
description: An orchestrator that analyzes tasks and delegates them to specialist agents
tools:
  - runSubagent
model: Claude Sonnet 4.5 (copilot)  # Needs strong task decomposition and decision-making
---

# Orchestrator Agent

You specialize in task analysis and delegation.
Analyze the user’s request and delegate appropriately to the following specialist agents:

- research-agent: Research and information gathering tasks (when web search is needed)
- implementation-agent: Code implementation tasks
- test-agent: Test generation and execution (routine work)
- git-agent: Version control tasks

Do not write code or manipulate files directly.
Always delegate to the appropriate specialist agent.

Each agent has its own toolset and model,
optimized for the nature of its tasks.

Available models:

Claude Sonnet 4.5 (copilot) – High-performance, well-balanced model

Claude Haiku 4.5 (copilot) – Fast, lightweight model

Claude Opus 4.5 (Preview) (copilot) – Top-tier performance (preview)

With this architecture:

Each agent’s toolset stays minimal
Tool selection becomes more accurate
Response time improves
Toolsets can be tailored to each task domain
Cost efficiency: Use Sonnet for complex reasoning, Haiku for routine tasks to optimize token usage
Performance: Choosing a model based on task complexity avoids unnecessary overhead

2. Isolating Background Agents with Git Worktrees

Background and Challenges

Background agents (Copilot CLI, OpenAI Codex, etc.) are designed to run tasks autonomously while you work in the editor.
Traditionally, their changes were applied directly to the workspace, which caused several problems:

Conflicts with files currently being edited by the user
Inability to safely run multiple background agents at once
Difficult to safely review and roll back the agent’s changes

Reference: Background Agents in VS Code

Solution: Git Worktrees

Git Worktrees are a Git feature that lets you create multiple working trees from the same repository.
In v1.107, VS Code automatically creates an independent worktree for each background agent session, providing complete isolation.

Reference: Branches & Worktrees - VS Code Source Control

How It Works

Main Workspace: /project/main
├── src/
├── package.json
└── ...

Background-agent Worktree: /project/.worktrees/session-abc123
├── src/           # Agent makes changes here
├── package.json
└── ...

All files created or modified by the agent live under the worktree folder, so the main workspace remains untouched.

How to Use

From the Chat view, select “New Background Agent”.
For Isolation mode, choose “Worktree” (the default is “Workspace”).
Enter a prompt to start the agent session.

┌─────────────────────────────────────┐
│  Isolation mode: [Worktree ▼]       │
│  ┌─────────────────────────────────┐│
│  │ Worktree  ← isolated mode       ││
│  │ Workspace ← direct changes      ││
│  └─────────────────────────────────┘│
└─────────────────────────────────────┘

Benefits

Aspect	Worktree mode	Workspace mode
Safety	High (fully isolated)	Low (direct changes)
Parallel run	Possible	Risk of conflicts
Review	Easy via diffs	Changes are applied directly
Rollback	Delete worktree and done	Requires Git revert

Merging Changes

When the agent finishes its task, you can bring its changes into the main branch via:

“Apply Changes” button – Apply worktree changes directly into the main branch.
Git operations – Merge or cherry-pick as with any normal branch.
Source Control view – Use the Repositories view to inspect the worktree and review diffs.

3. Integrating Custom Agents with Background Agents (Experimental)

What Are Custom Agents?

Custom agents let you define specialized AI assistants for particular roles or tasks.
They are configured in Markdown files, where you specify:

Persona (e.g. DBA specialist, frontend developer)
Available tools
Preferred language model
Guidelines and instructions

Reference: Custom Agents - VS Code Copilot Customization

Using Them in Background Agents

Previously, custom agents were only available in local chat sessions within VS Code.
With the v1.107 experimental feature, you can now assign custom agents to background agent sessions as well.

Reference: Use custom agents with background agents

Configuration

Enable the feature in settings:

   {
     "github.copilot.chat.cli.customAgents.enabled": true
   }

Create a custom agent in your workspace:

   <!-- .github/agents/code-reviewer.agent.md -->
   ---
   name: code-reviewer
   description: A code review expert focused on security and performance
   tools:
     - codebase
     - textSearch
   ---

   # Code Reviewer Agent

   You are an expert in security and performance.
   During code review, focus especially on:
   - Vulnerabilities such as SQL injection and XSS
   - Performance issues like N+1 queries
   - Proper error handling

When creating a background agent session, select the custom agent:

Example Use Cases

Custom agent	Background task
Code reviewer	Security audit of an entire PR
Test engineer	Generating test cases for new features
Documenter	Automatic API documentation generation
Refactoring expert	Modernizing legacy code

Combining with Git Worktrees

By combining custom agents with worktree isolation, you can fully control who (which persona) does what, and where (in a separate environment).

┌─────────────────────────────────────────────────────┐
│ Background agent session                            │
│                                                     │
│ Agent:     [code-reviewer]  ← Custom agent          │
│ Isolation: [Worktree]       ← Isolated mode         │
│ Task:      "Run a security review on this PR"       │
│                                                     │
│ → Specialized review                                │
│ → In a safe, isolated environment                   │
│ → Runs autonomously in the background               │
└─────────────────────────────────────────────────────┘

Notes on Tool Compatibility Across Environments

Custom agents can run in three main environments:

VS Code (GitHub Copilot Chat) – Interactive local IDE experience
GitHub.com (Copilot coding agent) – Cloud-side background execution
GitHub Copilot CLI – Command-line usage from the terminal

The same .agent.md definition can be shared across these environments, but supported tools and settings differ per environment.
In particular, some tools are specific to VS Code and unavailable on GitHub.com or in the CLI.
Unsupported tools or properties are simply ignored.

Because of this, behavior may differ depending on where the agent runs.
For example, an agent that works perfectly inside VS Code might run in a partially degraded mode on GitHub.com if certain tools are not available.

Custom agents are evolving rapidly, and supported properties and tools may change over time.
Check the latest official docs for details:

Reference links:

Custom agents configuration - GitHub Docs – Configuration properties and tool reference

About custom agents - GitHub Docs – Concept and basic usage

Custom agents in VS Code – VS Code–specific features and settings

Custom agents for GitHub Copilot - GitHub Changelog – Feature announcement and latest updates

awesome-copilot – Community-maintained examples of custom agents

📋 Disclaimer

Important: This article was created through a conversation with Claude, and may contain inaccuracies in the following areas:

Exact setting and property names (such as chat.customAgentInSubagent.enabled)

Syntax used in custom agent implementation examples

Existence and numbers of GitHub Issues or reference links

Details of experimental features

Always verify the latest information using the official resources below:

VS Code Release Notes v1.107

Custom agents configuration - GitHub Docs

VS Code Copilot Documentation

Summary

The GitHub Copilot updates in VS Code v1.107 push toward a balance between agent autonomy and developer control.

Feature	Value
Subagents	Efficient context management and a solution to the “too many tools” problem Per-task tools & models
Git Worktree isolation	Safe parallel execution of background agents
Integration with custom agents	Specialized background tasks with tailored personas and tools

In particular, the orchestration pattern with subagents offers a promising architectural answer to tool overload.
By giving each specialist agent only the minimal toolset it needs, you can expect faster and more accurate behavior, consistent with the GitHub team’s findings.

Moreover, combining subagents with custom agents lets you assign an independent model to each subagent, enabling advanced optimizations:

Cost efficiency: Use Sonnet for complex reasoning, Haiku for routine work
Latency improvements: Choose models based on task complexity
Higher specialization: Tailor the model–tool combination to each domain

All of these features are still experimental, and will likely evolve based on user feedback.
If you’re on the Insiders build, it’s a good time to experiment and send feedback to the GitHub repositories.