Use fewer, larger skills with progressive disclosure via embedded resources
- 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
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
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