AI coding assistants can generate C# code, work with ASP.NET Core applications, write unit tests, and help developers integrate third-party libraries. However, there is one problem that becomes noticeable when working with a large NuGet ecosystem: an AI model may know the general API of a library but not the specific conventions, recommended patterns, or limitations of the version installed in your project.
For example, imagine asking an AI coding agent to implement retry logic using Polly. The agent may generate code based on an older API, overlook a recommended configuration pattern, or introduce unnecessary complexity because it does not know how your project uses the library.
Developers usually solve this by providing documentation, writing custom instructions, or adding examples to the repository. These approaches work, but maintaining separate instructions for every dependency becomes difficult.
A newer approach is to distribute AI agent skills directly through NuGet packages. A package can include a SKILL.md file containing instructions, examples, and library-specific guidance. An AI coding agent can discover these instructions and use them when working with that dependency.
This approach connects package documentation with AI-assisted development and helps developers provide more relevant guidance without manually maintaining a separate collection of instructions.
In this article, we will explore how NuGet-delivered skills work, how to discover them in a .NET project, how to make them available to AI coding agents, and how package maintainers can distribute their own skills.
Why AI Coding Agents Need Package-Specific Knowledge
When an AI coding agent works with a .NET project, it usually has access to source files, project configuration, package references, and documentation available in the repository.
However, that information does not always explain how a particular dependency should be used.
Consider an application that uses several NuGet packages:
Serilog for structured logging.
Polly for resilience and retry policies.
MediatR for request handling.
Entity Framework Core for database access.
FluentValidation for application validation.
Each library has its own conventions and recommended implementation patterns.
An AI agent might generate code that compiles but does not follow the library's recommended practices. It may also use an outdated API or overlook an important configuration requirement.
The problem becomes more noticeable when a package introduces new APIs or changes its recommended usage patterns. Model training data may not contain information about recently published versions.
Package-specific skills address this gap by providing additional instructions close to the dependency itself.
Instead of asking the model to reconstruct the correct usage from general knowledge, the skill gives it focused guidance about how to work with the package.
What Are NuGet-Delivered Agent Skills?
Agent skills are reusable instructions and resources that provide an AI coding agent with specialized knowledge.
A skill commonly contains a Markdown file named SKILL.md. The file includes metadata describing the skill and instructions explaining when and how an agent should use it.
A simple skill might look like this:
my-package/
│
└── skills/
└── SKILL.md
The file can contain information such as:
Recommended ways to use the library.
Common configuration patterns.
Code examples.
Known limitations.
Migration instructions.
Frequently encountered mistakes.
Testing and troubleshooting guidance.
For example, a logging library could provide a skill explaining how to configure structured logging, add contextual properties, handle exceptions, and avoid logging sensitive information.
When an AI agent works with that package, it can use the instructions instead of relying entirely on its general training knowledge.
The important part is that the skill is distributed alongside the NuGet package. This makes it possible for package maintainers to update the guidance when the library's APIs and recommended practices change.
A package-delivered skill is not a new type of NuGet dependency or a replacement for a library's documentation. It is an additional resource designed specifically for AI agents.
How NuGet Skills Work in a .NET Project
The basic idea is straightforward.
A NuGet package contains its normal assemblies, metadata, and other resources. It can also include one or more SKILL.md files.
When a developer restores the package, NuGet downloads its contents into the local package cache.
An AI skill discovery tool can then inspect the restored packages, find available skill files, and make their instructions accessible to the coding agent.
Consider a project that references a package named Markout.
After restoring the package, its contents may be available in the NuGet global packages directory.
On a Windows machine, the default location is:
%USERPROFILE%\.nuget\packages\
On macOS and Linux, the default location is:
~/.nuget/packages/
A package containing skills might have the following structure:
markout/
└── 0.40.0/
├── lib/
├── README.md
├── markout.nuspec
└── skills/
├── SKILL.md
├── markout-output-formats/
│ └── SKILL.md
└── markout-built-in-shapes/
└── SKILL.md
The AI agent does not need to load every instruction immediately. A discovery mechanism can identify which skills are available and load relevant instructions when a task requires them.
This is useful because a project may contain dozens of dependencies, while a particular development task may need guidance from only one or two packages.
Discovering Skills From NuGet Packages
One way to inspect package-delivered skills is through the .NET inspection tooling.
For example, the dotnet-inspect tool can inspect a package and display its available skill files.
A package can be examined using the following command:
dotnet-inspect package markout -S Skills
The output identifies the skill files available in the package.
You can also inspect skills available through a project file:
dotnet-inspect project MyApplication.csproj -S Skills
This approach is useful when you want to understand which dependencies provide AI-specific instructions without manually opening every package directory.
It also helps developers identify whether a particular package contains guidance for a task they are performing.
For example, if a project uses a testing library, you can inspect whether the package provides instructions for configuring mocks, creating test cases, or verifying HTTP requests.
The availability of a skill depends on the package and its maintainers. Not every NuGet package currently includes AI-specific instructions.
Using nuget-skills to Connect Packages With AI Agents
Another approach is to use the nuget-skills command-line tool.
It is a separate .NET tool designed to discover and load skills associated with NuGet dependencies. It supports multiple coding agents, including GitHub Copilot, Claude Code, Cursor, Codex, Windsurf, and other compatible environments.
Install the tool globally:
dotnet tool install -g nuget-skills
After installation, configure the agents that should receive access to the discovered skills.
For example, to configure GitHub Copilot:
nuget-skills install --agent copilot
You can verify the installation:
nuget-skills doctor
The diagnostic command checks the tool installation and its integration with the selected environment.
Once configured, the session-start integration can scan the project's NuGet dependencies and identify available skills.
You can also run the scan manually:
nuget-skills scan
The output identifies packages that provide skills and indicates whether the instructions were discovered locally or remotely.
For example, the output may look like this:
Scanning MyApplication.sln...
Found 2 package(s) with skills (of 47 total):
Contoso.Logging 3.1.1 [local] Structured logging patterns
Contoso.Http 2.0.0 [remote] HTTP client best practices
Use 'nuget-skills load <package>' to view a skill.
The example illustrates how an application can have many dependencies but only a subset may provide additional AI instructions.
You can inspect the instructions for a specific package:
nuget-skills load Contoso.Logging
The tool can identify the package version from the project configuration. You can also specify a version explicitly:
nuget-skills load Contoso.Logging --version 3.1.1
This makes it easier to provide package-specific instructions without copying documentation into every development prompt.
Understanding Local and Remote Skill Discovery
NuGet skill discovery can use two sources.
Local discovery checks whether the installed package contains a SKILL.md file.
Because NuGet already downloads package contents during restore, the skill file can be available locally without requiring another repository download.
Remote discovery checks the package's source repository on GitHub for a corresponding skill file. This can be useful when a package does not include a skill inside its published NuGet archive.
Remote discovery requires GitHub CLI to be installed and authenticated.
For example:
gh auth login
The tool can then use the package's repository information and version to locate the corresponding skill.
When a matching version tag is available, the tool can use that version to retrieve the relevant instructions. It can also fall back to the repository's default branch when appropriate.
The distinction matters because local skills are distributed with the package version, while remote skills depend on the state of the source repository and the discovery process.
For reproducible development environments, package-resident skills provide a useful advantage: the guidance can be tied directly to the dependency version being restored.
Remote discovery can provide additional flexibility, but developers should review the source and version of instructions before trusting them.
Controlling Which Package Skills Are Available
A large .NET solution may reference many NuGet packages. Loading every available skill into every AI session can introduce unnecessary context and increase token usage.
The nuget-skills tool provides project-level configuration to control which package skills are surfaced.
Run:
nuget-skills configure
The interactive configuration scans the project and allows you to select the packages whose skills should be included.
You can also manage the configuration through commands:
nuget-skills configure --add Contoso.Logging
nuget-skills configure --remove Contoso.Http
nuget-skills configure --list
The configuration is stored in a file named .nuget-skills.json.
For example:
{
"packages": [
"Contoso.Logging",
"Contoso.Messaging"
]
}
This file can be committed to source control so that team members use the same selected package skills.
It is important to understand that this configuration controls which skills appear during discovery. It does not prevent an explicitly requested skill from being loaded.
This gives teams a way to standardize the AI guidance used across a project without forcing every developer to configure the same packages manually.
Creating a Skill Inside Your Own NuGet Package
The approach is not limited to existing package maintainers. Organizations that publish internal NuGet packages can also distribute their own AI skills.
Suppose your company maintains an internal package named Contoso.Logging.
The package has specific requirements for structured logging, correlation IDs, exception handling, and sensitive-data filtering.
You can create a skill that teaches an AI coding agent how to use the library correctly.
Start by creating a skills directory in the package project.
Contoso.Logging/
│
├── Contoso.Logging.csproj
├── LoggerExtensions.cs
├── LoggingOptions.cs
│
└── skills/
└── SKILL.md
Create the SKILL.md file with YAML frontmatter and practical instructions.
---
name: contoso-logging
description: Use when configuring structured logging,
adding contextual properties, handling exceptions,
or integrating Contoso.Logging into a .NET application.
---
# Contoso.Logging
Use this skill when implementing logging functionality
with the Contoso.Logging package.
## Recommended Practices
- Use the shared logging configuration.
- Include correlation identifiers for request tracking.
- Use structured properties instead of string concatenation.
- Avoid logging passwords, access tokens, and personal data.
- Preserve the existing logging conventions.
## Exception Handling
Use the approved exception logging methods.
Do not log the same exception repeatedly at multiple
application layers unless additional context is required.
## Testing
Verify that log events contain the expected structured
properties and that sensitive values are not included.
The description in the YAML frontmatter helps the agent understand when the skill is relevant.
The instructions should focus on actionable guidance rather than repeating the package's complete API documentation.
Next, include the skills directory in the NuGet package.
Add the following configuration to the project file:
<ItemGroup>
<None Include="skills/**"
Pack="true"
PackagePath="skills/" />
</ItemGroup>
Build the package:
dotnet pack -c Release
The resulting NuGet package contains the skill file alongside the normal package contents.
You can inspect the generated package to verify that the skill directory is included before publishing it to your private or public NuGet feed.
When consumers install the package, the skill becomes available for discovery through compatible tooling.
Supporting Multiple Skills in One Package
Some libraries provide several features that require different implementation guidance.
For example, an ASP.NET Core package might include instructions for middleware configuration, authentication integration, exception handling, and performance optimization.
Instead of placing every instruction in one large file, maintainers can create multiple focused skills.
A package could use the following structure:
Contoso.AspNetCore/
│
├── skills/
│ ├── SKILL.md
│ ├── authentication/
│ │ └── SKILL.md
│ ├── middleware/
│ │ └── SKILL.md
│ └── performance/
│ └── SKILL.md
│
└── Contoso.AspNetCore.csproj
The main skill can provide general information, while the additional files cover specific development scenarios.
For repositories that generate multiple NuGet packages, maintainers can also use the packages field in the skill's frontmatter to associate a skill with specific package IDs.
For example:
---
name: contoso-http
description: Recommended HTTP client patterns.
packages: Contoso.Http*, Contoso.Core
---
This helps prevent a skill intended for one library from appearing as relevant to unrelated packages produced by the same repository.
Focused skills are generally easier to maintain, test, and update than a single document containing every possible development scenario.
Keeping NuGet Skills Reliable and Up to Date
Adding a SKILL.md file to a NuGet package is relatively simple. Maintaining useful instructions requires more attention.
An inaccurate skill can be worse than having no skill at all because it may encourage an AI agent to generate incorrect code with greater confidence.
Package maintainers should treat skills as part of the package's developer experience.
When a package changes its API, review the corresponding instructions and examples. If a new version introduces a different configuration approach, update the skill so that the agent receives guidance appropriate to the installed version.
Also test the instructions with actual coding agents.
A useful evaluation should examine whether the skill helps the agent produce correct code, whether it introduces unnecessary context, and whether the resulting implementation follows the package's intended conventions.
Avoid writing skills that simply repeat the README or list every available method. The strongest skills explain decisions that are not obvious from the API surface.
For example, instead of saying that a package supports HTTP retries, explain which failures should be retried, how to configure retry limits, and which operations should not be repeated automatically.
It is also important to review the security implications of package-delivered instructions. A skill is guidance for an AI agent, not a security boundary. It should not contain credentials, private configuration, or instructions that encourage unsafe command execution.
Teams should review package updates and skill changes through the same source-control and release processes used for other package content.
When NuGet-Delivered Skills Make Sense
NuGet-delivered skills are especially useful when a library has specialized conventions that an AI agent might not understand from its public API.
They are also valuable when package maintainers frequently update APIs and want to distribute matching guidance with each release.
For internal development teams, skills can standardize how AI agents use shared libraries across multiple applications.
However, not every package needs a skill. A small library with a straightforward API may not benefit enough to justify maintaining additional instructions.
Similarly, skills should not replace normal documentation, XML comments, unit tests, or API references. Those resources remain important for developers and tools that do not support the Agent Skills format.
The best results come when skills complement existing documentation by explaining practical usage patterns, project conventions, and common implementation mistakes.
Summary
NuGet-delivered agent skills provide a practical way to connect library-specific knowledge with AI-assisted .NET development.
By including a SKILL.md file inside a package, maintainers can distribute instructions, examples, and recommended patterns alongside the library itself. Tools such as nuget-skills can discover these instructions from installed packages or supported remote repositories and make them available to compatible coding agents.
For developers, this can reduce repeated prompting and help AI agents generate code that follows the conventions of the dependencies already used by the project.
For package maintainers, it creates another way to improve the developer experience without changing the library's public API.
The important part is to keep skills focused, version-aware, tested, and secure. When maintained properly, they can become a useful part of the NuGet ecosystem and make AI coding workflows more consistent across .NET projects.
Join the conversation! Your thoughts help the community grow.