dotnet / dotnet/skills

Use fewer, larger skills with progressive disclosure via embedded resources

Open
#35 2 comments 1 reaction 0 assignees View on GitHub
Dominant language
C#
Stars
5.4k
Forks
415
Avg merge
1d 5h
Merged PRs (30d)
81

Description

### Problem

Consider the UX of having many skills installed in GitHub Copilot:

Screenshot of `/skills` in Copilot

Image

That is a screenshot from my /skills list. I have added precisely **one** popular 3rd party dotnet-skills plugin. By shipping too many skills we risk overwhelming both users and agent context windows.

### Proposed solution

Instead of many narrowly-scoped skills, we should ship **one** primary dotnet skill that contains curated, structured reference materials. Here's what I'm talking about:

Example: skills/dotnet/SKILL.md

```md
# .NET

## Latest .NET versions

SDK | Runtime | Release Date
--- | --- | ---
11.0.XXX | 11.0.X | YYYY-MM-DD
11.0.XXX | 11.0.X | YYYY-MM-DD

## Guides

- [How to install .NET](references/install-dotnet.md)
- [Adding packages to a project](references/adding-packages.md)
- [Scaffolding .NET projects](references/scaffolding.md)
- etc.

## Concepts

- [Scripts/File-based Apps](references/file-based-apps.md) - write scripts using a single *.cs file.
- [Native AOT](references/native-aot.md) - build and publish native executables on any platform.
- [Source Generators](references/source-generators.md) - etc.
- etc.

## Library References

- [System.CommandLine](references/system-commandline.md)
- [Microsoft.Extensions.Hosting](references/microsoft-extensions-hosting.md)
- [Microsoft.Extensions.DependencyInjection](references/microsoft-extensions-dependencyinjection.md)
- etc.
```

A structure like this is completely in line with the [Agent Skills Specification](https://agentskills.io/specification#references/):

> Skills should be structured for efficient use of context:
> - Metadata (~100 tokens): The name and description fields are loaded at startup for all skills
> - Instructions (< 5000 tokens recommended): The full SKILL.md body is loaded when the skill is activated
> - Resources (as needed): Files (e.g. those in scripts/, references/, or assets/) are loaded only when required
>
> Keep your main SKILL.md under 500 lines. Move detailed reference material to separate files.
>
> Keep individual [reference files](https://agentskills.io/specification#file-references) focused. Agents load these on demand, so smaller files mean less use of context.

### `dotnet` skill scope

The main `dotnet` skill should set agents up for success when using .NET in new and existing projects. The scope for included reference material can include .NET, ASP.NET, System libraries, Microsoft.Extensions libraries, and anything else we consider "built-in" to .NET.

The `dotnet` skill and included resources should be:
- Broadly useful, not opinionated.
- Focus on filling in agents on newer, more modern features that aren't well represented in training data. Examples:
- Recommending `Host.CreateApplicationBuilder()` instead of `Host.CreateDefaultBuilder()`
- Properly documenting System.Commandline's new API, since all current models have years of training data on the 2.0.0 beta 4 API.

### Potential for other skills

We may consider having other general skills for:
- MSBuild
- F#
- (Maybe) task oriented skills like debugging so that they can be called with a slash command
- And so on.

Contributor guide

Open the contributing guide

Research direction

Review the current skill layout and the proposed skills/dotnet/SKILL.md structure, then compare it with the Agent Skills Specification’s guidance on metadata, instructions, and references. Define the scope and organization for a consolidated .NET skill, including which material belongs in embedded reference resources. Done means the structure and included scope are agreed and actionable for implementation.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
ai, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.