.NET Agent Skills: Teaching Your Coding Agent to Think in C#

You've asked your coding agent to add a health check endpoint to your ASP.NET Core service. It generates something plausible — but it registers the health check middleware in the wrong order, uses a deprecated overload, and misses the MapHealthChecks call entirely. You fix it manually, mutter something about "close enough," and move on. Two sprints later, a colleague hits the same problem with the same agent, makes the same corrections, and neither of you benefits from the other's experience.

This is the core limitation of general-purpose coding agents: they know a lot about a lot, but they lack the deep, opinionated knowledge that experienced .NET developers carry around in their heads. Microsoft's answer, shipped in early March 2026, is dotnet/skills — a curated repository of agent skills that give your coding assistant specialised .NET knowledge it can draw on automatically.

The skills follow an open standard called Agent Skills, which means they aren't locked to a single editor or agent. Claude Code, GitHub Copilot, VS Code, Visual Studio 2026, Codex CLI, and over twenty other tools all support the same format.

What is an agent skill?

An agent skill is a lightweight package of instructions, context, and optional scripts that a coding agent can discover and activate when it encounters a relevant task. Think of it as a colleague's brain dump on a specific topic — the kind of document you'd write for a new team member explaining how things actually work, not how the docs say they should work.

Each skill follows a progressive disclosure model:

1. Metadata (~100 tokens) — the skill's name and description, loaded at startup so the agent knows what's available
2. Instructions (<5,000 tokens) — the full SKILL.md body, loaded only when the agent decides the skill is relevant
3. Resources (as needed) — scripts, reference docs, and assets loaded on demand

This means installing dozens of skills doesn't bloat your agent's context window. The agent reads the short descriptions at startup, activates the right skill when it recognises a matching task, and only then loads the detailed instructions.

The SKILL.md format

Every skill lives in a directory containing at minimum a SKILL.md file. The format is deliberately simple — YAML frontmatter followed by Markdown:

---
name: my-skill
description: Does X when Y. Use when the developer asks about Z.
license: MIT
metadata:
  author: my-org
  version: "1.0"
---

Step-by-step instructions, examples, edge cases — whatever
helps the agent do the job well.

The frontmatter has only two required fields: name and description. The name must be lowercase with hyphens (matching the directory name), and the description should include trigger phrases that help the agent match the skill to incoming requests.

Optional fields include license, compatibility (for environment requirements like specific runtimes or tools), metadata (arbitrary key-value pairs), and the experimental allowed-tools field for pre-approving specific tool invocations.

A skill directory can also contain subdirectories:

my-skill/
├── SKILL.md          # Required: metadata + instructions
├── scripts/          # Optional: executable code
├── references/       # Optional: detailed documentation
└── assets/           # Optional: templates, schemas, configs

The key design decision is that reference material lives in separate files rather than in the main SKILL.md. This keeps the primary instructions concise (under 500 lines is recommended) whilst allowing rich supporting material that the agent can pull in when it needs deeper context.

What's in dotnet/skills

The dotnet/skills repository organises its content into ten focused plugins, each covering a distinct area of .NET development:

Each plugin contains multiple individual skills. The dotnet-diag plugin, for example, includes skills for analysing performance traces, diagnosing memory leaks, and interpreting crash dumps — tasks where generic AI knowledge frequently falls short.

Every skill merged into the repository goes through a validation process. The team runs a lightweight evaluator that scores the skill's effectiveness against a baseline, ensuring it genuinely improves outcomes before it ships.

Setting it up

Installation varies by editor, but the general pattern is the same: point your agent at the marketplace, install the plugins you want, and let the agent discover skills automatically.

Claude Code

# Add the dotnet/skills marketplace
/plugin marketplace add dotnet/skills

# Browse what's available
/plugin marketplace browse dotnet-agent-skills

# Install a specific plugin
/plugin install dotnet-diag@dotnet-agent-skills

# Reload after installation
/reload-plugins

Once installed, skills activate automatically when the agent encounters a matching task. You can also invoke a skill explicitly:

/dotnet-diag:analyzing-dotnet-performance

VS Code

In VS Code Insiders with GitHub Copilot, add the marketplace URL to your Copilot extension settings:

{
  "github.copilot.chat.skills.marketplaces": [
    "https://github.com/dotnet/skills"
  ]
}

Then browse and install skills through the Chat Customisations editor. Installed skills appear as slash commands in Copilot Chat.

Visual Studio 2026

Install the .github + MCP extension, which provides access to skills from multiple sources including dotnet/skills. Skills auto-invoke when the agent detects a relevant task, or you can hint at them in your prompts.

How skills change agent behaviour

To understand the practical difference, consider a common task: diagnosing a memory leak in a .NET service.

Without skills, a coding agent might suggest generic advice — "use a profiler," "check for event handler leaks," "look at IDisposable usage." Helpful in a textbook sense, but not actionable when you're staring at a production service consuming 4 GB of memory.

With the dotnet-diag plugin's memory analysis skill activated, the agent gains structured knowledge about the actual diagnostic workflow:

# The agent knows to suggest collecting a dump with dotnet-dump
dotnet-dump collect -p <pid> --output memory.dmp

# And to analyse it with specific SOS commands
dotnet-dump analyze memory.dmp
> dumpheap -stat
> dumpheap -type System.String -min 85000
> gcroot <address>

The skill provides the agent with the sequence of commands, what to look for in the output, and how to interpret the results — the kind of tribal knowledge that separates someone who has debugged memory issues from someone who has only read about it.

Similarly, the dotnet-msbuild plugin transforms how the agent handles build issues. Rather than guessing at MSBuild properties, it knows the correct diagnostic switches, understands binary log analysis with MSBuild Structured Log Viewer, and can walk through dependency resolution failures methodically.

Writing your own skills

The open standard means you're not limited to Microsoft's curated set. Any team can author skills that encode their specific patterns, conventions, and hard-won knowledge.

A minimal skill for your team's API conventions might look like this:

---
name: api-conventions
description: >
  Enforces team API design conventions for ASP.NET Core
  services. Use when creating new endpoints, controllers,
  or modifying API response shapes.
---

## Response envelope

All API responses must use the standard envelope:

- Success: `{ "data": <payload>, "meta": { ... } }`
- Error: `{ "error": { "code": "ERR_XXX", "message": "..." } }`

Never return raw arrays as top-level JSON responses.

## Endpoint naming

- Use kebab-case for route segments: `/order-items`, not `/orderItems`
- Collection endpoints return paginated results by default
- Use `PUT` for full replacement, `PATCH` for partial updates

## Validation

- Use FluentValidation, not data annotations
- Return 422 for validation failures, not 400
- Include field-level errors in the response envelope

Drop this into your repository's .claude/skills/ or equivalent directory, and your agent will enforce these conventions every time someone works on an API endpoint.

For more sophisticated skills, you can include scripts that the agent can execute. A skill for database migrations might include a script that checks for common EF Core migration pitfalls:

#r "nuget: Microsoft.EntityFrameworkCore.Design, 10.0.0"

// Validate that the migration doesn't contain breaking changes
var migrationFile = Args[0];
var content = File.ReadAllText(migrationFile);

if (content.Contains("DropColumn") || content.Contains("DropTable"))
{
    Console.WriteLine("WARNING: This migration contains destructive operations.");
    Console.WriteLine("Ensure you have a rollback plan before applying to production.");
}

The broader ecosystem

The dotnet/skills repository is Microsoft's first-party offering, but the open standard has sparked a broader ecosystem. Community-maintained skill sets have appeared for specific frameworks like Akka.NET, for opinionated project structures, and for integration with specific cloud providers.

The microsoft/skills repository (separate from dotnet/skills) serves as a broader catalogue that includes skills for Azure services, AI frameworks, and cross-platform development. The Agent Skills specification itself is maintained as an open standard with adoption from over twenty-six tools and platforms at the time of writing.

Common pitfalls

Installing everything at once. Each installed skill adds to the metadata the agent loads at startup. Whilst the progressive disclosure model keeps this lightweight, installing all ten plugins when you only work on web APIs adds noise to the skill matching process. Install what you actually use.

Expecting skills to replace documentation. Skills make agents better at applying knowledge, but they don't turn a junior agent into a senior one. Complex architectural decisions, trade-off analysis, and code review still benefit from human judgement. Skills are best at encoding repeatable patterns and diagnostic workflows.

Neglecting skill maintenance. Your custom skills encode your team's current conventions. When those conventions change — and they will — stale skills actively harm productivity by reinforcing outdated patterns. Treat skills like any other living documentation: review them during retrospectives and update them when practices evolve.

Overloading a single SKILL.md. The spec recommends keeping the main file under 500 lines and 5,000 tokens. If your skill needs extensive reference material, split it into separate files in the references/ directory. The agent loads these on demand, keeping the initial activation cost low.

Summary

• Agent Skills is an open standard for packaging domain knowledge that coding agents can discover and use automatically, supported by over twenty-six tools including Claude Code, GitHub Copilot, and Visual Studio 2026.
• dotnet/skills is Microsoft's curated repository of .NET-specific skills, organised into ten plugins covering core development, data access, diagnostics, build systems, testing, and more.
• Skills follow a progressive disclosure model — only the name and description are loaded at startup; full instructions load on activation; reference material loads on demand.
• The SKILL.md format is intentionally simple: YAML frontmatter with a name and description, followed by Markdown instructions.
• Custom skills let teams encode their specific conventions, diagnostic workflows, and architectural patterns so every developer on the team benefits from the same institutional knowledge.
• Start with the dotnet and dotnet-diag plugins, write custom skills for your team's conventions, and keep them maintained as your practices evolve.