A practical, code-heavy guide to building specialized Copilot agents for real-world development workflows
Introduction
Visual Studio 2026 pushes GitHub Copilot beyond simple chat assistance and into a more agentic workflow. In addition to agent mode, Visual Studio now supports built-in specialized agents and custom agents that you can define in your repository using .agent.md files. These agents can use workspace context, code understanding, terminal actions, and external tools such as MCP servers to solve larger tasks more autonomously. Custom agents require Visual Studio 2026 version 18.4 or later, while the broader 2026 release line continues to expand AI-related capabilities. (Microsoft Learn)
Visual Studio’s built-in agent experience already includes workflow-specific agents such as Debugger, Profiler, and Test, while custom agents let teams encode their own conventions, processes, and knowledge sources. Visual Studio also supports Agent Skills, commonly discovered from locations such as .github/skills/ in the repository or ~/.copilot/skills/ in the user profile, and recent updates added a find_symbol capability so agents can navigate code semantically rather than relying only on text search. (Microsoft Learn)
Why this matters
For years, AI coding assistants were strongest at isolated tasks:
- explain this method
- generate a test
- rewrite this loop
- suggest a regex
That is useful, but it is still very reactive.
With Visual Studio 2026, you can now shape Copilot into a specialized teammate. Instead of giving generic prompts repeatedly, you create agents that already know:
- how your team names things
- which tools they may use
- how they should reason about architecture
- what standards they should enforce
- which external systems they can consult
This makes the interaction more consistent, more scalable, and much closer to an internal engineering workflow. Microsoft’s current documentation describes custom agents as repository-defined .agent.md files with YAML frontmatter and Markdown instructions, exposed through the agent picker in Visual Studio 2026 Insiders and also callable via @agentname syntax. (Microsoft Learn)
What “agents” mean in Visual Studio 2026
There are really four layers to understand:
1. Agent mode
Agent mode is the execution style. You give Copilot a higher-level objective, and it can plan, edit files, invoke tools, run terminal commands, observe results, and iterate until the task is complete or blocked. (Microsoft Learn)
2. Built-in agents
Visual Studio provides specialized built-in agents such as:
@debugger@profiler@test
These agents are optimized for specific IDE-native workflows such as debugging, performance analysis, and unit testing. (Microsoft Learn)
3. Custom agents
These are the ones you define yourself. They live in:
.github/agents/
and use the .agent.md format. (Microsoft Learn)
4. MCP servers and skills
MCP extends your agents with external tools and systems, while skills provide reusable instruction packages discovered from known folders. In Visual Studio, MCP is explicitly positioned as a way to connect GitHub Copilot agent mode with external tools and services, and skills are automatically discovered from repository and user-profile locations. (Microsoft Learn)
Prerequisites
Before you start, make sure you have:
- Visual Studio 2026 or a recent supported build in the 2026 line for the newest agent features. (Microsoft Learn)
- A GitHub Copilot subscription for the Copilot-driven agent features documented by Microsoft. (Microsoft Learn)
- Visual Studio 2026 version 18.4 or later if you want to create and use custom agents specifically. (Microsoft Learn)
- A repository where you can place
.agent.mdfiles under.github/agents/. (Microsoft Learn)
How agent mode works
According to Microsoft’s documentation, agent mode differs from ordinary ask mode because it can:
- interpret a high-level task
- determine relevant context automatically
- edit code
- run terminal commands
- invoke tools
- observe build/test/tool output
- iterate until the goal is reached or more input is needed (Microsoft Learn)
That makes agent mode a strong fit for scenarios like:
- implementing a feature across several files
- generating tests and fixing failures
- refactoring code with symbol awareness
- validating conventions against team rules
- consulting external systems through MCP
Part 1 — The anatomy of a custom agent
A custom agent in Visual Studio is a Markdown file with YAML frontmatter.
Microsoft’s documented example looks like this pattern: name, description, optional model, optional tools, then Markdown instructions. (Microsoft Learn)
Minimal example
Create this file:
.github/agents/backend-reviewer.agent.md
Contents:
---
name: Backend Reviewer
description: Reviews backend code for architecture, reliability, and test quality
---
You are a backend reviewer for our team.
When reviewing code:
1. Check whether business logic is in application services rather than controllers.
2. Verify dependency injection is used consistently.
3. Check async methods for cancellation token propagation.
4. Check logging for structured properties.
5. Ensure public behavior is covered by tests.
Always explain:
- what is wrong
- why it matters
- how to fix it
- which file or method is affected
This is the smallest useful pattern: a description plus strong behavioral instructions.
Full example with model and tools
Microsoft documents that the frontmatter supports:
namedescriptionmodeltools
and notes that if model is omitted, the current model picker selection is used. If tools is omitted, all available tools are enabled. Tool names can vary by platform, so you should verify the names in Visual Studio’s tools UI. (Microsoft Learn)
Example:
---
name: Full Stack Dev
description: Full-stack development assistant with search, editing, terminal, and documentation lookup
model: claude-opus-4-6
tools: ["code_search", "readfile", "editfiles", "find_references", "runcommandinterminal", "getwebpages"]
---
You are a full-stack development assistant.
Your workflow:
1. Search the codebase to identify existing architectural patterns.
2. Read the relevant files before proposing changes.
3. Prefer minimal, incremental changes over broad rewrites.
4. After edits, run the build and tests.
5. If a failure occurs, diagnose the root cause and fix it.
6. Summarize all changes and any follow-up recommendations.
Coding rules:
- Keep controllers thin.
- Place domain logic in services.
- Use DTOs at boundaries.
- Add tests for all changed behavior.
- Preserve existing conventions unless the prompt explicitly asks for modernization.
Part 2 — Folder structure and conventions
Visual Studio expects custom agents under:
your-repo/
└── .github/
└── agents/
├── code-reviewer.agent.md
├── test-writer.agent.md
└── modernization.agent.md
That location is explicitly documented by Microsoft for custom agents. (Microsoft Learn)
A useful convention is to organize agents by role:
- review agents
- implementation agents
- architecture agents
- migration agents
- documentation agents
Example:
.github/agents/
├── api-reviewer.agent.md
├── xunit-test-writer.agent.md
├── efcore-performance.agent.md
├── legacy-modernizer.agent.md
└── docs-writer.agent.md
This gives your team a small catalog of reusable workflows.
Part 3 — Your first practical agent: a C# code review agent
Let us build an agent tailored for a .NET backend.
File: .github/agents/csharp-review.agent.md
---
name: C# Review
description: Reviews C# code for maintainability, correctness, async safety, and testability
tools: ["code_search", "readfile", "find_references"]
---
You are a senior C# reviewer.
Review code using these rules:
1. Naming and readability
- Public members use clear PascalCase names.
- Avoid abbreviations unless they are well-known domain terms.
- Method names should express intent, not implementation detail.
2. Async correctness
- Async methods should return Task or Task<T>, not void unless event handlers.
- Use CancellationToken where appropriate.
- Avoid blocking async code with .Result or .Wait().
3. Exceptions and logging
- Catch exceptions only when you can add useful context or recover.
- Log with structured logging placeholders.
- Do not swallow exceptions silently.
4. Architecture
- Keep controllers thin.
- Avoid mixing infrastructure concerns into domain logic.
- Prefer small focused services.
5. Testability
- Dependencies should be injected.
- Avoid hard-coded time, GUIDs, file paths, or environment access in business logic.
- Suggest unit tests for changed public behavior.
Output format:
- Findings
- Severity
- Suggested fix
- Example patch if useful
How to use it
Inside Visual Studio Copilot Chat, you can invoke it like this:
@C# Review Review the OrderService and identify async, logging, and architectural issues.
Or use the agent picker if your build exposes the picker UI. Microsoft notes that the picker is currently available in Visual Studio 2026 Insiders, while @ syntax is also supported. (Microsoft Learn)
Part 4 — A test-generation agent for xUnit
One of the strongest uses of custom agents is narrowing test generation to your team’s real style.
File: .github/agents/xunit-test-writer.agent.md
---
name: xUnit Test Writer
description: Generates xUnit tests aligned with repository conventions
tools: ["code_search", "readfile", "editfiles", "find_references"]
---
You are an expert .NET test author specializing in xUnit.
When asked to create tests:
1. Inspect existing test projects first.
2. Match naming conventions already used in the repository.
3. Prefer readable Arrange/Act/Assert structure.
4. Use FluentAssertions when already present.
5. Use mocks only where needed.
6. Cover successful behavior, edge cases, and failures.
7. Do not overfit to implementation details if behavior-based testing is possible.
Always:
- identify the most appropriate test project
- create tests in the same style as the repo
- explain any untestable areas caused by current design
Example prompt
@xUnit Test Writer Generate tests for PriceCalculationService and cover null input, rounding rules, and discount edge cases.
Example target code
public sealed class PriceCalculationService
{
public decimal Calculate(decimal basePrice, decimal discountPercent)
{
if (basePrice < 0)
throw new ArgumentOutOfRangeException(nameof(basePrice));
if (discountPercent < 0 || discountPercent > 100)
throw new ArgumentOutOfRangeException(nameof(discountPercent));
var discount = basePrice * (discountPercent / 100m);
return Math.Round(basePrice - discount, 2, MidpointRounding.AwayFromZero);
}
}
Example test output you would want the agent to generate
using FluentAssertions;
using Xunit;
public sealed class PriceCalculationServiceTests
{
private readonly PriceCalculationService _sut = new();
[Fact]
public void Calculate_Should_ReturnRoundedDiscountedPrice()
{
var result = _sut.Calculate(19.99m, 10m);
result.Should().Be(17.99m);
}
[Fact]
public void Calculate_Should_Throw_When_BasePriceIsNegative()
{
var action = () => _sut.Calculate(-1m, 10m);
action.Should().Throw<ArgumentOutOfRangeException>()
.WithParameterName("basePrice");
}
[Theory]
[InlineData(-1)]
[InlineData(101)]
public void Calculate_Should_Throw_When_DiscountPercentIsOutOfRange(decimal discountPercent)
{
var action = () => _sut.Calculate(100m, discountPercent);
action.Should().Throw<ArgumentOutOfRangeException>()
.WithParameterName("discountPercent");
}
[Fact]
public void Calculate_Should_ReturnOriginalPrice_When_DiscountIsZero()
{
var result = _sut.Calculate(100m, 0m);
result.Should().Be(100m);
}
[Fact]
public void Calculate_Should_ReturnZero_When_DiscountIsOneHundredPercent()
{
var result = _sut.Calculate(100m, 100m);
result.Should().Be(0m);
}
}
This is exactly where agents outperform generic prompting: they can be taught what “good tests” mean in your repository.
Part 5 — A modernization agent for legacy .NET code
Modernization is one of the most practical use cases for agent mode because it usually spans many files and involves repeated verification. Microsoft has separately highlighted modernization-oriented agent workflows for .NET, and agent mode is specifically designed to iterate through changes and validation cycles. (Microsoft Learn)
File: .github/agents/dotnet-modernizer.agent.md
---
name: .NET Modernizer
description: Helps modernize legacy .NET code incrementally and safely
tools: ["code_search", "readfile", "editfiles", "find_references", "runcommandinterminal"]
---
You are a .NET modernization specialist.
When modernizing code:
1. First identify the current framework, package versions, and architectural style.
2. Prefer safe incremental improvements over large rewrites.
3. Preserve behavior unless explicitly told otherwise.
4. Replace obsolete APIs with supported alternatives.
5. Update nullability, dependency injection, configuration, and logging patterns where appropriate.
6. Run build and tests after each significant change.
7. Summarize compatibility risks and any manual follow-up steps.
Focus on:
- nullable reference types
- async/await improvements
- DI-friendly services
- logging abstractions
- minimal breaking changes
Example prompt
@.NET Modernizer Update this project to modern dependency injection and configuration patterns, but keep behavioral changes minimal.
Part 6 — Creating a domain-specific agent for APIs
Agents become especially useful when they encode local architecture rules.
File: .github/agents/rest-api-guardian.agent.md
---
name: REST API Guardian
description: Enforces API design consistency, validation, and error handling
tools: ["code_search", "readfile", "find_references", "editfiles"]
---
You are an API architecture agent.
When reviewing or implementing endpoints:
1. Verify route naming is resource-oriented and consistent.
2. Ensure HTTP verbs match the operation semantics.
3. Validate DTOs at the boundary.
4. Ensure proper status code handling.
5. Check whether error payloads follow repository conventions.
6. Keep controllers thin and move logic into services.
7. Check request/response models for backwards-compatible evolution.
Prefer:
- explicit validation
- consistent response contracts
- cancellation token support
- pagination for collection endpoints
Example controller before improvement
[ApiController]
[Route("api/[controller]")]
public class OrdersController : ControllerBase
{
private readonly AppDbContext _dbContext;
public OrdersController(AppDbContext dbContext)
{
_dbContext = dbContext;
}
[HttpPost("create")]
public async Task<IActionResult> Create(OrderDto dto)
{
if (dto == null)
return BadRequest();
var entity = new Order
{
CustomerId = dto.CustomerId,
Amount = dto.Amount,
CreatedAt = DateTime.UtcNow
};
_dbContext.Orders.Add(entity);
await _dbContext.SaveChangesAsync();
return Ok(entity.Id);
}
}
Example of what your agent should steer toward
[ApiController]
[Route("api/orders")]
public sealed class OrdersController : ControllerBase
{
private readonly IOrderService _orderService;
public OrdersController(IOrderService orderService)
{
_orderService = orderService;
}
[HttpPost]
[ProducesResponseType(typeof(CreateOrderResponse), StatusCodes.Status201Created)]
[ProducesResponseType(typeof(ValidationProblemDetails), StatusCodes.Status400BadRequest)]
public async Task<ActionResult<CreateOrderResponse>> Create(
[FromBody] CreateOrderRequest request,
CancellationToken cancellationToken)
{
var result = await _orderService.CreateAsync(request, cancellationToken);
return CreatedAtAction(
nameof(GetById),
new { id = result.OrderId },
result);
}
[HttpGet("{id:guid}")]
[ProducesResponseType(typeof(OrderResponse), StatusCodes.Status200OK)]
[ProducesResponseType(StatusCodes.Status404NotFound)]
public async Task<ActionResult<OrderResponse>> GetById(
Guid id,
CancellationToken cancellationToken)
{
var order = await _orderService.GetByIdAsync(id, cancellationToken);
return order is null ? NotFound() : Ok(order);
}
}
This is where a custom agent helps enforce a stable architectural direction across the whole codebase.
Part 7 — Using Visual Studio-specific tools
Microsoft’s examples for Visual Studio-specific custom agents include tools such as:
code_searchreadfileeditfilesfind_referencesruncommandinterminalgetwebpages(Microsoft Learn)
They also note that tool names vary across Copilot platforms, so you should verify the actual tool names shown in your Visual Studio installation. (Microsoft Learn)
A practical strategy is:
- start narrow
- only enable the tools the agent truly needs
- add terminal or web access only when the workflow requires it
For example:
Review-only agent
tools: ["code_search", "readfile", "find_references"]
Implementation agent
tools: ["code_search", "readfile", "editfiles", "find_references"]
Build-and-verify agent
tools: ["code_search", "readfile", "editfiles", "find_references", "runcommandinterminal"]
Docs-aware implementation agent
tools: ["code_search", "readfile", "editfiles", "find_references", "getwebpages"]
This keeps the agent predictable and reduces unnecessary capability exposure.
Part 8 — Extending your agent with MCP
One of the most important recent additions is MCP support in Visual Studio. Microsoft describes MCP as the standard way for AI models to interact with external tools and services, and explicitly notes that Visual Studio can use MCP servers in agent mode. MCP servers may run locally or remotely. (Microsoft Learn)
That means your custom agent is not limited to source files. It can, through MCP, potentially reason over things like:
- internal docs
- design systems
- APIs
- issue trackers
- databases
- style guides (Microsoft Learn)
Why MCP is powerful
Without MCP, your agent is mostly limited to repository-local context plus whatever web/document lookup is otherwise available.
With MCP, your agent can become a real workflow orchestrator.
Example scenarios:
- A release agent that checks build metadata and deployment rules
- A support triage agent that queries issue history
- An architecture agent that reads ADRs from an internal documentation system
- A database migration agent that consults schema information before generating migrations
Conceptual architecture
Visual Studio 2026
-> Copilot Agent Mode
-> Custom Agent (.agent.md)
-> Tools
-> Repository Context
-> MCP Server(s)
-> Docs
-> APIs
-> Databases
-> Issue systems
Example: agent instructions that assume MCP-backed conventions
---
name: Architecture Guardian
description: Uses repository context and architecture docs to validate changes
tools: ["code_search", "readfile", "find_references", "getwebpages"]
---
You are an architecture governance agent.
When reviewing changes:
1. Inspect affected code paths and dependencies.
2. Compare implementation choices against the architecture decision records available through connected tools.
3. Flag layer violations, hidden coupling, and cross-boundary leakage.
4. Prefer established patterns over introducing parallel abstractions.
5. If repository conventions and architecture docs conflict, explicitly highlight the conflict.
Notice the key design idea: the agent prompt should describe how to reason, not just what files to touch.
Part 9 — Agent Skills: reusable building blocks
Microsoft’s March update notes that Visual Studio can automatically pick up skills from locations such as:
.github/skills/~/.copilot/skills/
Each skill lives in its own directory and contains a SKILL.md file following the Agent Skills specification. When activated, the skill appears in the chat so you know it is being applied. (Microsoft for Developers)
When to use a skill instead of an agent
Use an agent when you want a named, specialized persona or workflow entry point.
Use a skill when you want reusable domain knowledge or operational behavior that can be applied by agents when relevant.
Good agent use cases
- Code review
- Architecture validation
- Test generation
- Legacy modernization
Good skill use cases
- Internal coding standards
- Team release checklist
- EF Core migration conventions
- Security review rubric
- Common prompt assets for a vertical domain
Example skill layout
.github/skills/
└── efcore-migrations/
└── SKILL.md
Example SKILL.md:
# EF Core Migration Rules
Use this skill when changing persistence models or entity mappings.
Rules:
1. Prefer additive changes over destructive changes.
2. Never drop a column without checking for backward compatibility.
3. Review index implications.
4. Generate migration names that describe business intent.
5. Always verify whether seed data or value converters are affected.
A strong combination is:
- one custom agent for database work
- several skills that encode your migration, performance, and naming rules
Part 10 — The find_symbol advantage
One of the more important practical enhancements is the find_symbol capability described in Microsoft’s March update. It gives agents language-aware navigation, including symbol references, declarations, scope, and type information. That makes refactoring scenarios far safer and more precise than plain text search. (Microsoft for Developers)
This matters for prompts like:
Rename this method and update all call sites.
or
Move this service interface and fix all references.
or
Change this parameter type and update downstream usage safely.
Without semantic navigation, an agent might guess based on text patterns. With symbol-aware tooling, it can reason at the language-service level instead. (Microsoft for Developers)
Example scenario
Suppose you have this service:
public interface ICurrencyConverter
{
decimal Convert(decimal amount, string fromCurrency, string toCurrency);
}
And you want to modernize it to a richer request object:
public sealed record CurrencyConversionRequest(
decimal Amount,
string FromCurrency,
string ToCurrency);
public interface ICurrencyConverter
{
decimal Convert(CurrencyConversionRequest request);
}
A symbol-aware agent has a much better chance of updating all call sites correctly, especially across larger solutions.
Part 11 — A complete end-to-end example
Let us walk through a realistic setup for a .NET web API project.
Step 1 — Create the agent file
.github/agents/dotnet-feature-builder.agent.md
---
name: .NET Feature Builder
description: Implements .NET features following repository conventions and verifies them with tests
tools: ["code_search", "readfile", "editfiles", "find_references", "runcommandinterminal"]
---
You are a senior .NET feature implementation agent.
Implementation process:
1. Understand the existing architecture before editing anything.
2. Reuse existing abstractions where possible.
3. Keep changes minimal and cohesive.
4. Update or add tests for changed behavior.
5. Run build and relevant test commands after edits.
6. If the build fails, diagnose and fix the issue before stopping.
Code quality rules:
- Controllers stay thin.
- Business logic belongs in services.
- DTOs define API boundaries.
- Use async/await end to end when appropriate.
- Use structured logging.
- Follow the repository’s naming and test conventions.
Output requirements:
- Summarize changed files
- Explain design decisions
- Call out risks or deferred follow-up work
Step 2 — Invoke it in agent mode
Prompt:
@.NET Feature Builder Add an endpoint to return all active subscriptions for a customer, using the same response style and architecture as the existing Orders endpoints.
Step 3 — Let the agent inspect the solution
A strong agent should now:
- search for existing subscription and order patterns
- inspect controllers and service layers
- locate DTO naming conventions
- create the endpoint, service method, and tests
- run build/tests
- iterate if failures occur
That behavior aligns directly with Microsoft’s description of agent mode as an iterative workflow that can edit code, run commands, and respond to tool output. (Microsoft Learn)
Part 12 — Example implementation code the agent might produce
Request/response models
public sealed record SubscriptionResponse(
Guid SubscriptionId,
Guid CustomerId,
string PlanCode,
DateTimeOffset StartDate,
DateTimeOffset? EndDate,
bool IsActive);
Service contract
public interface ISubscriptionService
{
Task<IReadOnlyList<SubscriptionResponse>> GetActiveByCustomerAsync(
Guid customerId,
CancellationToken cancellationToken);
}
Service implementation
public sealed class SubscriptionService : ISubscriptionService
{
private readonly AppDbContext _dbContext;
private readonly ILogger<SubscriptionService> _logger;
public SubscriptionService(
AppDbContext dbContext,
ILogger<SubscriptionService> logger)
{
_dbContext = dbContext;
_logger = logger;
}
public async Task<IReadOnlyList<SubscriptionResponse>> GetActiveByCustomerAsync(
Guid customerId,
CancellationToken cancellationToken)
{
_logger.LogInformation(
"Loading active subscriptions for customer {CustomerId}",
customerId);
return await _dbContext.Subscriptions
.Where(x => x.CustomerId == customerId && x.IsActive)
.OrderBy(x => x.StartDate)
.Select(x => new SubscriptionResponse(
x.Id,
x.CustomerId,
x.PlanCode,
x.StartDate,
x.EndDate,
x.IsActive))
.ToListAsync(cancellationToken);
}
}
Controller endpoint
[ApiController]
[Route("api/customers/{customerId:guid}/subscriptions")]
public sealed class CustomerSubscriptionsController : ControllerBase
{
private readonly ISubscriptionService _subscriptionService;
public CustomerSubscriptionsController(ISubscriptionService subscriptionService)
{
_subscriptionService = subscriptionService;
}
[HttpGet("active")]
[ProducesResponseType(typeof(IReadOnlyList<SubscriptionResponse>), StatusCodes.Status200OK)]
public async Task<ActionResult<IReadOnlyList<SubscriptionResponse>>> GetActive(
Guid customerId,
CancellationToken cancellationToken)
{
var subscriptions = await _subscriptionService
.GetActiveByCustomerAsync(customerId, cancellationToken);
return Ok(subscriptions);
}
}
Unit test
public sealed class SubscriptionServiceTests
{
[Fact]
public async Task GetActiveByCustomerAsync_Should_ReturnOnlyActiveSubscriptions()
{
var options = new DbContextOptionsBuilder<AppDbContext>()
.UseInMemoryDatabase(Guid.NewGuid().ToString())
.Options;
await using var dbContext = new AppDbContext(options);
var logger = new LoggerFactory().CreateLogger<SubscriptionService>();
var customerId = Guid.NewGuid();
dbContext.Subscriptions.AddRange(
new Subscription
{
Id = Guid.NewGuid(),
CustomerId = customerId,
PlanCode = "BASIC",
StartDate = DateTimeOffset.UtcNow.AddDays(-30),
IsActive = true
},
new Subscription
{
Id = Guid.NewGuid(),
CustomerId = customerId,
PlanCode = "OLD",
StartDate = DateTimeOffset.UtcNow.AddDays(-200),
EndDate = DateTimeOffset.UtcNow.AddDays(-1),
IsActive = false
});
await dbContext.SaveChangesAsync();
var sut = new SubscriptionService(dbContext, logger);
var result = await sut.GetActiveByCustomerAsync(customerId, CancellationToken.None);
Assert.Single(result);
Assert.Equal("BASIC", result[0].PlanCode);
}
}
That is the kind of cohesive multi-file result a custom agent should produce well.
Part 13 — Best practices for writing effective agents
Here are the patterns that consistently produce better results.
1. Be specific about process
Do not just say “review code.”
Say:
- inspect existing patterns first
- prefer minimal changes
- run tests after changes
- explain risks
- preserve architecture
Bad:
You are a coding assistant. Help with backend code.
Better:
You are a backend implementation agent.
First inspect existing controller and service patterns.
Then implement minimal changes aligned with those patterns.
Run tests after edits and fix failures before stopping.
2. Encode constraints, not just goals
Good agents say what must not happen.
Example:
Do not introduce a new abstraction if an existing service pattern already solves the problem.
Do not move business logic into controllers.
Do not change public contracts unless explicitly asked.
3. Keep agents role-based
One giant “do everything” agent is usually weaker than a small set of focused agents.
Good split:
API GuardianxUnit Test Writer.NET ModernizerArchitecture Guardian
4. Limit tools when possible
Least-necessary tooling keeps behavior cleaner.
5. Make output expectations explicit
For example:
Always output:
- changed files
- why each change was made
- any open risks
- suggested next steps
That greatly improves consistency.
Part 14 — Common mistakes
Mistake 1: Writing vague instructions
Help with our codebase.
This gives the model very little structure.
Mistake 2: Turning the agent into a policy dump
Huge instruction walls can reduce clarity. Prefer concise, prioritized rules.
Mistake 3: Over-authorizing tools
Do not enable terminal or web access unless the scenario benefits from them.
Mistake 4: Ignoring repository conventions
Your agent should explicitly tell Copilot to inspect existing patterns first.
Mistake 5: Using one agent for every workflow
Reviewing, implementing, testing, and architecture planning are related but distinct tasks.
Part 15 — A recommended starter set for .NET teams
If I were setting this up for a professional .NET team in Visual Studio 2026, I would start with these five agents:
1. csharp-review.agent.md
For maintainability, async correctness, logging, and architecture review.
2. xunit-test-writer.agent.md
For repository-aligned tests.
3. dotnet-feature-builder.agent.md
For implementing features end to end.
4. dotnet-modernizer.agent.md
For legacy cleanup and safe migration work.
5. architecture-guardian.agent.md
For ensuring layer boundaries and ADR alignment.
Then I would add skills for:
- logging conventions
- EF Core migration rules
- REST contract standards
- security review checklist
- performance investigation checklist
Part 16 — Further reading
Here are the most useful official or near-official starting points for going deeper:
- Use built-in and custom agents with GitHub Copilot in Visual Studio — the core documentation for built-in agents, custom agents,
.agent.mdstructure, and tool configuration. (Microsoft Learn) - Get started with GitHub Copilot agent mode in Visual Studio — explains how agent mode plans, edits, runs commands, uses tools, and iterates. (Microsoft Learn)
- Use MCP Servers in Visual Studio — the key reference for connecting external tools and services into the Visual Studio agent workflow. (Microsoft Learn)
- Visual Studio March Update – Build Your Own Custom Agents — useful for agent skills,
find_symbol, and current 2026-era agent improvements. (Microsoft for Developers) - Custom Agents in Visual Studio: Built in and Build-Your-Own agents — practical product-context overview from the Visual Studio team. (Microsoft for Developers)
- Extend your coding agent with .NET Skills — useful if you want reusable .NET-focused skill packages that work with coding agents, including Visual Studio. (Microsoft for Developers)
- Visual Studio 2026 Release Notes — useful to track which agent features are in which release wave. (Microsoft Learn)
Conclusion
Visual Studio 2026 changes the agent story from “ask a smart chatbot for code help” to “define repeatable engineering behavior directly inside your repository.” Microsoft’s current platform now supports agent mode, specialized built-in agents, custom .agent.md agents, MCP integration, skills, and semantic symbol navigation, which together make it possible to build highly targeted assistants for your team’s real workflows. (Microsoft Learn)
The real breakthrough is not just automation. It is consistency.
A well-written custom agent helps your team:
- preserve architecture
- standardize review quality
- generate better tests
- modernize code safely
- reduce repetitive prompting
- turn tribal knowledge into reusable engineering assets
If you work in .NET, C#, or multi-project enterprise solutions, this is one of the most interesting capabilities in the current Visual Studio generation.
Summary
Visual Studio 2026 lets you go far beyond ordinary Copilot chat by combining agent mode, built-in specialized agents, and custom agents defined in .github/agents/*.agent.md. These custom agents use YAML frontmatter plus Markdown instructions and can be constrained with specific tools such as code_search, readfile, editfiles, find_references, and terminal access. In recent 2026 releases, Microsoft has also expanded the surrounding ecosystem with MCP support, Agent Skills, and find_symbol for semantic navigation across codebases. (Microsoft Learn)
The best way to use this feature is to create small, role-focused agents instead of one generic all-purpose assistant. Strong examples include a C# review agent, an xUnit test writer, a .NET modernization agent, and an API architecture guardian. The most effective agents are explicit about process, constraints, repository conventions, and expected output. When combined with MCP and skills, they become much more than prompt templates: they become reusable development workflows embedded directly into your repository. (Microsoft Learn)
Views: 0
