Skills and markdown are a new and quickly growing kind of engineering tool. They can deliver insight from experts directly into an agent context window in the moment you need it. In the past, developers would have to search through forum posts looking for some syntax or tool pattern to accomplish a task. The open question is what the relationship should be between agents, skill repos, and the dotnet CLI. This high-level design proposes a loosely coupled approach that brings insight closer while maintaining meaningful architectural separation.
The basis of the proposal is to reduce the distance between agent and official skills while reducing the blast radius of misbehaving skills. .NET is a popular dev platform. We need to be careful about that.
dotnet/skills
The team is doing a good job of publishing expert skills in the dotnet/skills repo. The skills cover a broad set of .NET components and workflows. One guesses that very few .NET developers are aware of this repo. The traffic data (available to any repo) is significantly lower than popular dotnet org repos. It really should grow to be one of the highest since the audience is broader. We can improve visibility by advertising it via the dotnet CLI.
Skills are installed via a combination of marketplace.json and plugin.json. You can learn more about those via some walkthroughs I created.
The governance model of dotnet/skills is out of scope for this document. It is controlled by the same team that controls the SDK.
The skills apply to all .NET versions. Any version differentiation is covered within a given skill.
There isn't a good feedback loop for skills. This plan doesn't propose a new feedback mechanism, just to increase users. That's likely the best approach for getting more feedback.
dotnet skill
A skill command is the natural choice to expose skills. It isn't entirely obvious how it should relate to the repo and to the agent marketplace/plugin/skill acquisition experience.
I'll start with the actual proposal and then explain why it is the best choice.
$ dotnet skill
# .NET agent skills
Curated set of .NET skills and custom agents for coding agents, maintained in the [dotnet/skills](https://github.com/dotnet/skills) repo.
| Plugin | Description |
| --- | --- |
| `dotnet` | Collection of core .NET skills for handling common .NET coding tasks. |
| `dotnet-data` | Skills for .NET data access and Entity Framework related tasks. |
| `dotnet-diag` | Skills for .NET performance investigations, debugging, and incident analysis. |
| `dotnet-msbuild` | Comprehensive MSBuild and .NET build skills: failure diagnosis, performance optimization, code quality, and modernization. |
| `dotnet-nuget` | NuGet and .NET package management: dependency management and modernization. |
| `dotnet-upgrade` | Skills for migrating and upgrading .NET projects across framework versions, language features, and compatibility targets. |
| `dotnet-maui` | Skills for .NET MAUI development: environment setup, diagnostics, troubleshooting, navigation, data binding, dependency injection, layout, and theming. |
| `dotnet-ai` | AI and ML skills for .NET: technology selection, LLM integration, agentic workflows, RAG pipelines, MCP, and classic ML with ML.NET. |
| `dotnet-template-engine` | .NET Template Engine skills: template discovery, project scaffolding, and template authoring. |
| `dotnet-test` | Skills for running, diagnosing, and migrating .NET tests: test execution, filtering, platform detection, and MSTest workflows. |
| `dotnet-aspnet` | ASP.NET Core web development skills including middleware, endpoints, real-time communication, and API patterns. |
| `dotnet11` | Skills for new .NET 11 APIs and language features. |
## Install
Run in your agent (Claude Code, Copilot CLI, and others supporting the plugin spec):
```
/plugin marketplace add dotnet/skills
/plugin install <name>@dotnet-agent-skills
```
Notes:
- The trust model is the same as
dotnet/skills itself. That assumption needs to be validated.
- The content from the command is sourced from a remote source, primarily from
marketplace.json. The dotnet skill command doesn't include much hard-coded content, perhaps just the title and first paragraph.
- That means that the
dotnet skill content stays fresh and that we can change it if a new model requires a change in wording or due to some other reason.
- Singular
skill is chosen so that we can consistently use the command in multiple places. It is more likely that the singular framing will be generally appropriate. For example, I used skill with my dotnet-inspect tool since it has a single skill to print to stdout. skill also aligns with singular tool and other CLI commands.
- As plugins are added or deleted, that change will be reflected in the
marketplace.json file that dotnet skill downloads.
- We could just expose a URL instead of this content. The rendered content is equally usable by both humans and agents while the URL requires more context to interpret.
Alternate approaches
There are two other significant camps of ideas to consider.
Include skills with the SDK -- We could ship skills in the SDK. That would certainly solve the acquisition problem. However, it works quite poorly with agent acquisition. Agents enable two primary experiences: remote repos and current repo. The other challenge is that the SDK path changes on each servicing.
Another major problem is that the SDK is used for both developer and prod scenarios. Many teams take a new SDK as a signal to re-run CI and to re-deploy services to production. "Hey self, there is a new SDK. I know that those fine .NET folks only ship a new servicing release for serious reasons. I'll do the right thing and disturb my perfectly good running app in prod with this new important release".
The point is that we can never ever ever ever let ourselves be put into a position where we need to ship an off-cycle SDK solely due to a misbehaving skill. Doing that would be indicative of a terrible design choice. Like never.
Download skills to a local repo -- We could ship a skill downloader that downloads skills to a local repo. This idea has more merit since it plays much more nicely with agent skill acquisition. There are three challenges with this idea. Developers have to do this in each repo, each repo will end up with slightly different skill content due to drift, and our expert team will completely lose the ability to update the content since it is locked up in a million different repos. If we do discover that skills are misbehaving, there is nothing we can do about it through some central change.
There are probably other ideas, but they likely pattern match on these two other approaches.
Command Discovery
There will be zero agents and no training data mention of dotnet skill at ship. As a result, we can expect zero uptake. That's both a blessing and a curse. Recall that we don't want to service the SDK for badly behaving commands that get picked up in a million agent sessions in a single day.
However, once dotnet skill becomes known, we will have a contract that agents are likely to act on. That's the point where we need to worry about a million agent sessions accessing our skills repo. It's unknown what that behavior will be.
We should experiment with AGENT.md content that triggers agents the desired amount. Once we get that right, we should share that with users and encourage them to add it to their AGENT.md files.
The intent of the AGENT.md text should be something like:
If you run into trouble with C# code or .NET APIs, run dotnet skill. It prints out a set of curated skill plugins that are available remotely that can be installed in the agent environment.
There is no claim that this text is exactly hitting the target, however, it is intended as broadly descriptive of what we need to communicate to the agent. This text may also change over time.
We could expose the "trigger text" via a flag like dotnet skill --agent. This content would be stored in agent-trigger.md in the dotnet/skills repo. Exposing the text would enable developers to refresh their AGENT.md files over time to avoid drift.
Network challenges
This proposal intentionally requires a network call to access marketplace.json. That creates latency and availability challenges. There are a few ways to solve this, offered in preferred order:
- Print "skills are unavailable" if the network is unavailable.
- Cache locally and check for updates with some expiry/TTL scheme.
- Include a copy of
marketplace.json in the SDK and check for updates remotely.
A major consideration is that the entire experience is network bound. It doesn't help much to rely on a local copy of marketplace.json if the developer is doing development in a submarine (with no remote network access).
Opportunities
This approach could be expanded to enable other opportunities.
- Include high-value skill content related to the specific version of the SDK, like high-value new features or behavior changes.
- List AI-adjacent tools that are effectively an extension of the SDK and available via nuget.org if not already installed. This experience becomes most relevant as we adopt a faster pace shipping option for this category of tools.
Closing
Skills appear to be quite useful and because of that will likely be enduring. It's true that models will learn more and more, however, they'll never be able to predict differing preferences and approaches across repos and teams. Skills are excellent for last mile enablement. It makes sense to help pave that last mile.
There is significant opportunity for anti-patterns with a feature that attempts to close the gap between the agent and skill repo, as discussed in the alternative approaches. marketplace.json and plugin.json already work fine, enabling anyone to install skills from dotnet/skills today. The biggest gap is realizing that there is an official skills repo for your dev stack. Agents don't tell you that. This is the problem that this proposal aims to solve, in the lightest touch way possible.
Skills and markdown are a new and quickly growing kind of engineering tool. They can deliver insight from experts directly into an agent context window in the moment you need it. In the past, developers would have to search through forum posts looking for some syntax or tool pattern to accomplish a task. The open question is what the relationship should be between agents, skill repos, and the dotnet CLI. This high-level design proposes a loosely coupled approach that brings insight closer while maintaining meaningful architectural separation.
The basis of the proposal is to reduce the distance between agent and official skills while reducing the blast radius of misbehaving skills. .NET is a popular dev platform. We need to be careful about that.
dotnet/skills
The team is doing a good job of publishing expert skills in the dotnet/skills repo. The skills cover a broad set of .NET components and workflows. One guesses that very few .NET developers are aware of this repo. The traffic data (available to any repo) is significantly lower than popular dotnet org repos. It really should grow to be one of the highest since the audience is broader. We can improve visibility by advertising it via the
dotnetCLI.Skills are installed via a combination of
marketplace.jsonandplugin.json. You can learn more about those via some walkthroughs I created.The governance model of dotnet/skills is out of scope for this document. It is controlled by the same team that controls the SDK.
The skills apply to all .NET versions. Any version differentiation is covered within a given skill.
There isn't a good feedback loop for skills. This plan doesn't propose a new feedback mechanism, just to increase users. That's likely the best approach for getting more feedback.
dotnet skill
A
skillcommand is the natural choice to expose skills. It isn't entirely obvious how it should relate to the repo and to the agent marketplace/plugin/skill acquisition experience.I'll start with the actual proposal and then explain why it is the best choice.
Notes:
dotnet/skillsitself. That assumption needs to be validated.marketplace.json. Thedotnet skillcommand doesn't include much hard-coded content, perhaps just the title and first paragraph.dotnet skillcontent stays fresh and that we can change it if a new model requires a change in wording or due to some other reason.skillis chosen so that we can consistently use the command in multiple places. It is more likely that the singular framing will be generally appropriate. For example, I usedskillwith my dotnet-inspect tool since it has a single skill to print tostdout.skillalso aligns with singulartooland other CLI commands.marketplace.jsonfile thatdotnet skilldownloads.Alternate approaches
There are two other significant camps of ideas to consider.
Include skills with the SDK -- We could ship skills in the SDK. That would certainly solve the acquisition problem. However, it works quite poorly with agent acquisition. Agents enable two primary experiences: remote repos and current repo. The other challenge is that the SDK path changes on each servicing.
Another major problem is that the SDK is used for both developer and prod scenarios. Many teams take a new SDK as a signal to re-run CI and to re-deploy services to production. "Hey self, there is a new SDK. I know that those fine .NET folks only ship a new servicing release for serious reasons. I'll do the right thing and disturb my perfectly good running app in prod with this new important release".
The point is that we can never ever ever ever let ourselves be put into a position where we need to ship an off-cycle SDK solely due to a misbehaving skill. Doing that would be indicative of a terrible design choice. Like never.
Download skills to a local repo -- We could ship a skill downloader that downloads skills to a local repo. This idea has more merit since it plays much more nicely with agent skill acquisition. There are three challenges with this idea. Developers have to do this in each repo, each repo will end up with slightly different skill content due to drift, and our expert team will completely lose the ability to update the content since it is locked up in a million different repos. If we do discover that skills are misbehaving, there is nothing we can do about it through some central change.
There are probably other ideas, but they likely pattern match on these two other approaches.
Command Discovery
There will be zero agents and no training data mention of
dotnet skillat ship. As a result, we can expect zero uptake. That's both a blessing and a curse. Recall that we don't want to service the SDK for badly behaving commands that get picked up in a million agent sessions in a single day.However, once
dotnet skillbecomes known, we will have a contract that agents are likely to act on. That's the point where we need to worry about a million agent sessions accessing our skills repo. It's unknown what that behavior will be.We should experiment with
AGENT.mdcontent that triggers agents the desired amount. Once we get that right, we should share that with users and encourage them to add it to theirAGENT.mdfiles.The intent of the
AGENT.mdtext should be something like:There is no claim that this text is exactly hitting the target, however, it is intended as broadly descriptive of what we need to communicate to the agent. This text may also change over time.
We could expose the "trigger text" via a flag like
dotnet skill --agent. This content would be stored inagent-trigger.mdin the dotnet/skills repo. Exposing the text would enable developers to refresh theirAGENT.mdfiles over time to avoid drift.Network challenges
This proposal intentionally requires a network call to access
marketplace.json. That creates latency and availability challenges. There are a few ways to solve this, offered in preferred order:marketplace.jsonin the SDK and check for updates remotely.A major consideration is that the entire experience is network bound. It doesn't help much to rely on a local copy of
marketplace.jsonif the developer is doing development in a submarine (with no remote network access).Opportunities
This approach could be expanded to enable other opportunities.
Closing
Skills appear to be quite useful and because of that will likely be enduring. It's true that models will learn more and more, however, they'll never be able to predict differing preferences and approaches across repos and teams. Skills are excellent for last mile enablement. It makes sense to help pave that last mile.
There is significant opportunity for anti-patterns with a feature that attempts to close the gap between the agent and skill repo, as discussed in the alternative approaches.
marketplace.jsonandplugin.jsonalready work fine, enabling anyone to install skills from dotnet/skills today. The biggest gap is realizing that there is an official skills repo for your dev stack. Agents don't tell you that. This is the problem that this proposal aims to solve, in the lightest touch way possible.