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

> Learn to integrate dotnet/skills into your .NET projects. Discover how to register the marketplace, install plugins, and invoke skills without direct code embedding. Get the complete guide.

- Repository: [.NET Platform/skills](https://github.com/dotnet/skills)
- Tags: how-to-guide
- Published: 2026-07-08

---

**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](https://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`](https://github.com/dotnet/skills/blob/main/plugins/dotnet/skills/setup-local-sdk/SKILL.md) defines the local SDK installation workflow.
- **[`eng/skill-validator/src/Shared/PluginDiscovery.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Shared/PluginDiscovery.cs)** — Runtime helper used for plugin discovery and validation, useful for debugging integration issues.

All [`SKILL.md`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/.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`](https://github.com/dotnet/skills/blob/main/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`<br>`/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

```bash

# 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:

```yaml

# .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`](https://github.com/dotnet/skills/blob/main/SKILL.md). For `setup-local-sdk`, the payload structure is:

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

```

The agent executes the underlying script (such as [`install-dotnet.sh`](https://github.com/dotnet/skills/blob/main/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:

```csharp
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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/global.json) | Verify [`global.json`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/SKILL.md) file (located at `plugins/<plugin>/skills/<skill-name>/SKILL.md`) for specific version requirements before integration.