# Architecture of the dotnet/skills Repository: A Modular Plugin-Based Toolbox

> Explore the modular plugin architecture of the dotnet/skills repository. Discover how AI capabilities are isolated, validated, and orchestrated for efficient development.

- Repository: [.NET Platform/skills](https://github.com/dotnet/skills)
- Tags: architecture
- Published: 2026-07-06

---

**The dotnet/skills repository implements a modular, plugin-based architecture that isolates reusable AI capabilities into self-contained packages under `plugins/`, validates them through the `eng/skill-validator` engine, and orchestrates execution via JSON manifests and automated CI pipelines.**

The dotnet/skills repository functions as a comprehensive toolbox for AI-assisted .NET development, organizing its capabilities through a distinct architectural pattern that emphasizes modularity and testability. This architecture separates skills into isolated plugins, centralizes validation logic in the `eng` directory, and maintains strict contracts between components to ensure reliable agent execution across Copilot, Claude, and CodeX marketplaces.

## Core Components of the Architecture

### Plugin Layer (plugins/)

Each plugin resides under `plugins/` (e.g., `plugins/dotnet/`, `plugins/dotnet-msbuild/`, `plugins/dotnet-upgrade/`) and functions as a self-contained unit that can be installed independently via AI assistant marketplaces. Every plugin contains a [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest and [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) documentation that declare the skill's binaries, scripts, and execution contracts to the runtime.

The self-contained nature of plugins means users can install only the capabilities they need. For example, the `plugins/dotnet-msbuild/` directory houses MSBuild-focused skills for diagnosis and performance analysis, while `plugins/dotnet-upgrade/` contains modernization agents for migrating .NET projects.

### Validation Engine (eng/)

The `eng/skill-validator/` directory houses the core tooling that powers skill validation, evaluation, and coverage reporting. The project file located at `eng/skill-validator/src/SkillValidator.csproj` implements the automated test runner that executes against each skill, gathers metrics, and produces validation reports consumed by the CI pipeline defined in [`.github/workflows/skill-validator.yml`](https://github.com/dotnet/skills/blob/main/.github/workflows/skill-validator.yml).

This engine ensures that every skill conforms to expected contracts before merging. The corresponding unit tests in `eng/skill-validator/tests/SkillValidator.Tests.csproj` verify that skills properly handle inputs and outputs according to the defined schema.

### Documentation and Test Suites

Documentation resides in `docs/` (including [`docs/agentic-workflows.md`](https://github.com/dotnet/skills/blob/main/docs/agentic-workflows.md) which details agent orchestration patterns) and plugin-specific [`README.md`](https://github.com/dotnet/skills/blob/main/README.md) files. Comprehensive test suites under `tests/` (e.g., `tests/dotnet-upgrade/`, `tests/dotnet-msbuild/`, `tests/dotnet-ai/`) exercise skills against realistic scenarios including .NET project migrations, MSBuild failure analysis, and AI RAG pipelines.

## How Skills Execute Within the Architecture

### Skill Definition and Registration

Skills are defined by a [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) file and [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest that specify required assets and command structures. When users install a plugin via CLI commands, the marketplace loads the manifest and registers the skill with the runtime:

```bash
/plugin marketplace add dotnet/skills
/plugin install dotnet-msbuild@dotnet-agent-skills

```

### Runtime Execution Flow

When an agent invokes a skill, the runtime loads assets from the plugin folder, executes the defined command (often a `dotnet` CLI invocation), and returns structured JSON output. The following C# example demonstrates how agents interact with the skill architecture:

```csharp
var result = await Agent.RunSkillAsync(
    skillName: "dotnet-msbuild/diagnose",
    input: new { ProjectPath = "./MyApp.csproj" });
Console.WriteLine(result.Output);

```

### Validation and CI Integration

The `eng/skill-validator` automatically detects new skills by scanning the `plugins/` directory and executes the corresponding test suites from `tests/` on every pull request. Developers can run the validator locally using PowerShell:

```powershell
cd eng/skill-validator
dotnet test

```

Results are processed by the evaluation pipeline and posted to a public dashboard. This design means adding a new skill requires only creating a folder under `plugins/` and adding tests under `tests/`—no central code changes are necessary.

## Key Implementation Files

| File | Description |
|------|-------------|
| [`README.md`](https://github.com/dotnet/skills/blob/main/README.md) | Overview of the repository and installation instructions. |
| [`plugins/dotnet/README.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet/README.md) | Core .NET language-server skill definitions. |
| [`plugins/dotnet-msbuild/README.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-msbuild/README.md) | MSBuild-focused skills for diagnosis and modernization. |
| `eng/skill-validator/src/SkillValidator.csproj` | Project file for the validation engine. |
| `eng/skill-validator/tests/SkillValidator.Tests.csproj` | Unit tests ensuring skill contract compliance. |
| `tests/dotnet-upgrade/` | End-to-end migration scenarios for validation. |
| [`docs/agentic-workflows.md`](https://github.com/dotnet/skills/blob/main/docs/agentic-workflows.md) | Design notes on agent orchestration patterns. |

## Summary

- The architecture organizes capabilities into **self-contained plugins** under `plugins/` that install independently via marketplace integrations.
- The **`eng/skill-validator`** engine automatically validates skills against test suites in `tests/` and publishes metrics through CI pipelines defined in [`.github/workflows/skill-validator.yml`](https://github.com/dotnet/skills/blob/main/.github/workflows/skill-validator.yml).
- Skills declare contracts through **[`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json)** manifests and **[`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md)** files, executing via standardized JSON inputs and outputs.
- The design supports **horizontal scaling**—new skills require only folder creation under `plugins/` and test implementation without modifications to central validation code.

## Frequently Asked Questions

### What is the purpose of the [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest in the dotnet/skills architecture?

The [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest declares the skill's metadata, required binaries, scripts, and execution parameters to the runtime. Located in each plugin folder under `plugins/`, this file enables the marketplace to register the skill and ensures agents load the correct assets when invoking commands via the standardized contract.

### How does the validation engine handle new skills added to the repository?

The `eng/skill-validator` automatically scans the `plugins/` directory to discover new skills and executes the corresponding test suites from `tests/` on every pull request. This design means developers need only create a new folder under `plugins/` with the implementation and add tests under `tests/` for automatic validation and dashboard reporting.

### Can plugins in the dotnet/skills repository be installed independently?

Yes, each plugin under `plugins/` is self-contained and can be installed independently through AI assistant marketplaces such as Copilot, Claude, or CodeX. Users add the repository as a marketplace source and install specific plugins via CLI commands without consuming the entire repository, enabling selective capability deployment.

### What programming languages are used in the dotnet/skills validation engine?

The validation engine located in `eng/skill-validator/` is implemented in C#, as evidenced by the `SkillValidator.csproj` project file and associated unit tests in `SkillValidator.Tests.csproj`. This engine integrates with the .NET CLI to execute skill tests and process results into JSON metrics for the CI dashboard.