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

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 manifest and 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.

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 which details agent orchestration patterns) and plugin-specific 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 file and 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:

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

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:

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	Overview of the repository and installation instructions.
plugins/dotnet/README.md	Core .NET language-server skill definitions.
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	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.
• Skills declare contracts through plugin.json manifests and 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 manifest in the dotnet/skills architecture?

The 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.

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