How to Integrate dotnet/skills with Other .NET Projects: A Complete Guide

You integrate dotnet/skills by registering the skills marketplace with /plugin marketplace add dotnet/skills, installing specific plugins via /plugin install <plugin>@dotnet-agent-skills, and invoking skills through declarative contracts—no direct code embedding or NuGet package references required.

The dotnet/skills repository is a collection of reusable Agent Skills that follow the open standard defined at agentskills.io. Each skill lives in its own plugin folder under plugins/ and can be consumed by any .NET project that invokes an agent, such as Copilot CLI, Claude Code, Codex CLI, or Cursor. This guide covers the repository structure, installation methods, and runtime integration patterns to incorporate these skills into your development workflow.

Understanding the Repository Structure

The dotnet/skills repository organizes capabilities into discrete, self-contained units:

• plugins/ — Top-level folder containing independent plugins (e.g., dotnet, dotnet-upgrade, dotnet-test). Each plugin represents a domain-specific capability set.

• plugins/dotnet/ — Core .NET & C# language-server (LSP) skill set, containing foundational skills for SDK management and project operations.

• plugins/dotnet/skills/<skill-name>/SKILL.md — Individual skill definitions combining Markdown documentation with YAML metadata. For example, plugins/dotnet/skills/setup-local-sdk/SKILL.md defines the local SDK installation workflow.

• eng/skill-validator/src/Shared/PluginDiscovery.cs — Runtime helper used for plugin discovery and validation, useful for debugging integration issues.

All SKILL.md files under plugins/**/skills/**/ describe the skill contract (inputs, outputs, and workflow). Agents read this metadata to determine how to invoke the underlying implementation.

How Agent Skills Are Discovered and Executed

The integration follows a marketplace-based discovery pattern:

1. Marketplace registration — The repository publishes a marketplace manifest (.agents/plugins/marketplace.json).
2. Agent-side discovery — Compatible agents query this manifest to present available plugins and skills.
3. Installation — Users execute commands like /plugin install dotnet@dotnet-agent-skills to copy plugin files into the agent's plugin directory.
4. Skill invocation — The agent parses the skill's SKILL.md, validates required inputs against the YAML front-matter, and executes the associated script or SDK command.

Because the skill contract is declarative (Markdown + YAML), you do not embed the skill's code into your project; you reference it via the agent infrastructure.

Installation Methods for .NET Projects

You have two primary pathways to integrate skills, depending on your use case:

Method	Use Case	Commands
Agent-based	Interactive development or chat-based workflows	/plugin marketplace add dotnet/skills/plugin install <plugin>@dotnet-agent-skills
Skill-installer CLI	Scripted environments or reproducible CI/CD pipelines	skill-installer install https://github.com/dotnet/skills/tree/main/plugins/<plugin>/skills/<skill-name>

Both approaches result in the same directory structure under the agent's plugin home (e.g., ~/.cursor/plugins/ or the Copilot CLI plugin store).

Example: Installing the setup-local-sdk Skill

# Register the dotnet marketplace (one-time per agent)

codex plugin marketplace add dotnet/skills

# Install the core dotnet plugin (contains multiple skills)

codex plugin install dotnet@dotnet-agent-skills

# Optional: Pull specific skill files into your repo for CI

skill-installer install \
  https://github.com/dotnet/skills/tree/main/plugins/dotnet/skills/setup-local-sdk

After execution, the setup-local-sdk folder appears in your repository. You can then reference it in GitHub Actions:

# .github/workflows/dotnet-sdk.yml

name: Local SDK Setup
on: [push]
jobs:
  install:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install local .NET SDK
        run: |
          cd plugins/dotnet/skills/setup-local-sdk
          bash install-dotnet.sh

The skill depends only on official dotnet-install scripts, requiring no additional NuGet references in your project.

Invoking Skills at Runtime from .NET Applications

When calling a skill, supply a JSON payload matching the Inputs table defined in the skill's SKILL.md. For setup-local-sdk, the payload structure is:

{
  "channelOrVersion": "11.0",
  "quality": "preview",
  "jq": true
}

The agent executes the underlying script (such as install-dotnet.sh) and returns a success object containing the installed SDK version and logs.

Programmatic Invocation Using the Codex SDK

You can trigger skills from C# applications using the OpenAI/Codex SDK:

using OpenAI;
using OpenAI.Chat;

var client = new OpenAIClient("<your-api-key>");

var request = new ChatRequest()
{
    Model = "gpt-4o-mini",
    Messages =
    {
        new ChatMessage(ChatRole.System, "You are a .NET agent."),
        new ChatMessage(ChatRole.User,
            @"{
                ""skill"": ""dotnet/setup-local-sdk"",
                ""input"": {
                    ""channelOrVersion"": ""11.0"",
                    ""quality"": ""preview"",
                    ""jq"": true
                }
            }")
    }
};

var response = await client.Chat.CompleteAsync(request);
Console.WriteLine(response.Choices[0].Message.Content);

Note: This code demonstrates embedding skill invocations within chat requests. The actual transport and execution are handled by the Codex or Copilot service, not by your project's build process.

Common dotnet/skills Integration Scenarios

Scenario	Plugin/Skill	Workflow
Upgrade legacy projects	dotnet-upgrade (e.g., migrate-nullable-references)	Run skill from agent, review suggested changes, apply diff to repository
Test execution and analysis	dotnet-test (e.g., run-tests, analyse-test-coverage)	Invoke in CI to execute tests and feed results back to agents for recommendations
MAUI workload installation	dotnet-maui (install-maui-workload)	Installs workload into local .dotnet/ SDK without system-wide changes
Project scaffolding	dotnet-template-engine (create-from-template)	Generates projects, writes global.json, and updates .gitignore
Performance diagnostics	dotnet-diag (e.g., collect-traces)	Runs dotnet-trace/dotnet-counters and returns collected logs

All scenarios follow the same pattern: install the plugin, invoke the skill, and process the agent-handled result.

Updating and Versioning Skills

Maintain current skill versions using these commands:

• Update a plugin: /plugin update <plugin>@dotnet-agent-skills
• Version resolution: The repository follows semantic versioning per plugin, but agents typically resolve the newest commit on the main branch unless a specific version tag is provided.

When customizing skills, ensure the SKILL.md front-matter remains synchronized with your logic changes so agents can validate inputs automatically.

Troubleshooting dotnet/skills Integration Issues

Symptom	Cause	Solution
"paths ignored" error	Host dotnet version < 10	Install .NET 10+ system-wide (see Prerequisites in each skill's documentation)
Agent cannot locate skill	Marketplace not added or plugin not installed	Re-run /plugin marketplace add dotnet/skills and reinstall the plugin
Local SDK not used after install	Missing or incorrect global.json	Verify global.json contains "paths": [".dotnet","$host$"] (see Step 7 in setup-local-sdk documentation)
CI job hangs on download	Network restrictions	Ensure outbound HTTPS to https://dot.net is allowed; the skill uses official install script URLs

Summary

• Register the marketplace once using /plugin marketplace add dotnet/skills to enable discovery.
• Install plugins via /plugin install <plugin>@dotnet-agent-skills or use skill-installer for CI/CD scenarios.
• Reference skills declaratively through SKILL.md contracts rather than embedding code directly into your projects.
• Update regularly using /plugin update to access new capabilities and bug fixes.
• Validate environment requirements (specifically .NET 10+ for certain skills) before invocation.

Frequently Asked Questions

Do I need to add NuGet packages to use dotnet/skills?

No. The dotnet/skills repository does not require NuGet package references in your project. Skills are consumed through agent interfaces (Copilot CLI, Codex, etc.) or the skill-installer CLI, which downloads the skill definitions (Markdown + scripts) directly. The only external dependencies are the official dotnet-install scripts used by specific skills like setup-local-sdk.

Can I use dotnet/skills in automated CI/CD pipelines?

Yes. Use the skill-installer CLI to download skill files into your repository during pipeline initialization. For example, running skill-installer install https://github.com/dotnet/skills/tree/main/plugins/dotnet/skills/setup-local-sdk places the skill scripts in your working directory, allowing subsequent steps to execute bash install-dotnet.sh or equivalent commands without interactive agent sessions.

How do I update skills to the latest version?

Run /plugin update <plugin>@dotnet-agent-skills from your agent interface to fetch the latest changes from the main branch. The repository follows semantic versioning, but agents typically resolve to the newest commit unless you specify a version tag. For CI environments, re-run the skill-installer command to pull updated skill definitions.

What .NET version is required to run these skills?

Most skills require .NET 10 or later on the host machine, particularly for capabilities like setup-local-sdk that manage local SDK installations. Check the Prerequisites section in each skill's SKILL.md file (located at plugins/<plugin>/skills/<skill-name>/SKILL.md) for specific version requirements before integration.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}