Proposal: NuGet Agent Assets — package-distributed skills for .NET coding agents

[mo3in]

Summary

I propose a .NET/NuGet convention for libraries and workloads to ship versioned, agent-readable skills alongside their assemblies.

When a package is referenced, its skills become discoverable to developers and supported agent hosts. They should not be silently loaded into an agent context. A developer, organization policy, or agent host must explicitly preview and enable them.

This would make the .NET ecosystem more agent-friendly while preserving developer control and supply-chain safety.

Motivation

Many .NET packages and workloads have conventions that a general-purpose agent cannot reliably infer from APIs alone: source generators, analyzers, AOT and trimming requirements, lifecycle constraints, platform-specific configuration, test execution, and integration patterns.

Today, each application repository must separately maintain framework guidance in files such as AGENTS.md or CLAUDE.md. That guidance can become stale and does not naturally match the exact resolved package version.

NuGet already provides a versioned dependency graph. This proposal adds a versioned guidance graph.

Design principles

1. Skills are immutable package assets, versioned with the package.
2. Discovery is automatic; activation is explicit.
3. Transitive packages never silently add instructions to an agent context.
4. Skills use an open, portable format such as SKILL.md.
5. The SDK/NuGet client exposes metadata; agent hosts decide how to consume enabled skills.
6. Skills use progressive disclosure: concise routing guidance with focused references and examples.
7. Package authors own compatibility and maintenance for their published skill.

Proposed package layout

/
  lib/
  build/
  agents/
    manifest.json
    skills/
      dotnet-maui/
        SKILL.md
        references/
          lifecycle.md
          navigation.md
          platform-setup.md

Example agents/manifest.json:

{
  "schemaVersion": 1,
  "skills": [
    {
      "id": "dotnet-maui",
      "name": ".NET MAUI",
      "description": "Guidance for building, debugging, testing, and publishing .NET MAUI applications.",
      "entryPoint": "skills/dotnet-maui/SKILL.md",
      "appliesTo": {
        "languages": [ "C#" ],
        "projectCapabilities": [ "maui" ]
      }
    }
  ]
}

I suggest a dedicated agents/ package folder rather than contentFiles: skills should remain immutable package assets for tools to discover, not files copied into the consuming project.

SDK authoring experience

Package authors could opt in during packing:

<PropertyGroup>
  <PackAgentAssets>true</PackAgentAssets>
</PropertyGroup>

<ItemGroup>
  <AgentSkill Include="agents/skills/dotnet-maui/**" />
</ItemGroup>

dotnet pack would validate the manifest, asset paths, required skill metadata, size limits, and unsafe path constructs.

Consumer and CLI experience

After restore, the SDK can discover agent assets from resolved packages:

dotnet agent skills list
dotnet agent skills list --include-transitive
dotnet agent skills preview Microsoft.Maui.Controls
dotnet agent skills enable Microsoft.Maui.Controls
dotnet agent skills export --format agentskills

Example output:

Direct package skills

Microsoft.Maui.Controls 10.0.0
  Skill: dotnet-maui
  Purpose: Build, debug, test, and publish .NET MAUI applications
  Status: available, not enabled

IDEs and agent hosts could provide an equivalent UI: preview the content, inspect the package identity/version/source/hash, and enable it per project or workspace.

Trust and security model

Package-provided skills must be treated as untrusted content until explicitly enabled. Suggested defaults:

• Discover skills only from direct PackageReference dependencies.
• Do not auto-activate skills, including those from direct dependencies.
• Never execute code merely because a skill is discovered or enabled.
• Show package ID, version, feed, publisher, and content hash before enabling.
• Respect lock files and signed-package verification.
• Allow organization policy to allow-list package IDs, publishers, feeds, or signatures.
• Support a checked-in approval file for reproducible CI behavior.
• Keep the existing agent consent boundary for commands, secret access, infrastructure changes, and external actions.

For example:

{
  "version": 1,
  "approvedSkills": [
    {
      "packageId": "Microsoft.Maui.Controls",
      "packageVersion": "10.0.0",
      "skillId": "dotnet-maui",
      "contentHash": "..."
    }
  ]
}

.NET MAUI example

A MAUI package or workload could ship one dotnet-maui skill covering:

• App startup and dependency injection through MauiProgram
• Shell navigation, routes, page lifecycle, XAML, compiled bindings, resources, MVVM, and theming
• Android, iOS, macOS, and Windows platform lifecycle/configuration differences
• Permissions, device APIs, and conditional platform code
• Testing MAUI applications and view models
• Workload, Android SDK, Xcode, JDK, simulator/emulator troubleshooting
• Publishing, signing, trimming, Native AOT, and store deployment

This gives an agent the version-appropriate and platform-aware guidance it needs, instead of relying on generic .NET advice.

Proposed rollout

Phase 1: Specification

• Define the agents/manifest.json schema and package layout.
• Define discovery, direct/transitive semantics, and threat-model guidance.
• Reuse or align with the open Agent Skills SKILL.md format.

Phase 2: NuGet/SDK support

• Validate assets during dotnet pack.
• Surface resolved agent assets through restore data or a discovery API.
• Add dotnet agent skills list and preview.
• Add explicit enable/export support.

Phase 3: Ecosystem integrations

• IDE and coding-agent discovery of approved skills.
• NuGet Gallery presentation of agent assets.
• Organization policy and allow-lists.
• Reference implementations for .NET MAUI, ASP.NET Core, Aspire, EF Core, and other major workloads.

Open questions

• Should direct dependencies be the default discovery boundary?
• Should approvals live in project configuration, a lock file, user settings, or all three?
• How should signing and trusted publishers affect approval?
• Should dotnet agent be a first-party CLI surface, or should the SDK only expose discovery APIs for agent hosts?
• How should skill evaluations be packaged and validated without adding excessive complexity?
• How can the system avoid overwhelming agent context when a project contains many packages?

I would welcome feedback on whether this belongs primarily in NuGet, the .NET SDK, Visual Studio/Copilot integration, or a cross-repository design effort.