# How to Structure Plugins in dotnet/skills: Complete Directory and Manifest Guide

> Learn how to structure plugins in dotnet/skills. Create plugin directories with manifest and definition files for seamless integration. Get the complete guide here.

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

---

**To structure a plugin in dotnet/skills, create a directory under `plugins/` containing a [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest and a `skills/` subdirectory with [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) definition files.**

The dotnet/skills repository organizes AI capabilities into modular, discoverable units called plugins. Understanding how to structure plugins in dotnet/skills correctly ensures compatibility with the Agents Skills runtime and marketplace discovery. Each plugin follows a strict convention validated during CI against the schema defined in [`eng/skill-validator/src/Models.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Models.cs).

## Top-Level Plugin Directory Structure

Every plugin resides under the `plugins/` directory with a name that serves as its canonical identifier. The folder name must match the `"name"` field in [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) exactly, as this identifier is used by the marketplace and CLI tooling.

The repository contains several established plugins demonstrating this pattern:

- `plugins/dotnet/` – Core .NET skills
- `plugins/dotnet-nuget/` – NuGet-related capabilities  
- `plugins/dotnet11/` – .NET 11 API features
- `plugins/dotnet-maui/` – MAUI framework support

## Required Files and Layout

Inside each plugin directory, the runtime expects a specific structure. The core `dotnet` plugin illustrates the canonical layout:

```

plugins/dotnet/
├─ plugin.json
├─ README.md
├─ lsp.json
└─ skills/
    ├─ csharp-scripts/
    │   └─ SKILL.md
    └─ dotnet-pinvoke/
        ├─ SKILL.md
        └─ references/
            └─ type-mapping.md

```

The [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest is mandatory at the root, while [`README.md`](https://github.com/dotnet/skills/blob/main/README.md) and [`lsp.json`](https://github.com/dotnet/skills/blob/main/lsp.json) remain optional but recommended.

## The plugin.json Manifest

Every plugin must contain a [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) file at its root defining metadata and entry points. The runtime enforces this schema strictly; missing required fields cause validation failures during CI execution.

Required fields include:

- **`name`**: The plugin identifier matching the folder name
- **`version`**: Semantic version string  
- **`description`**: Human-readable summary for the marketplace
- **`skills`**: Relative path to the skills directory (typically `"./skills/"`)
- **`lspServers`** (optional): Path to LSP configuration file

Example from [`plugins/dotnet/plugin.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet/plugin.json):

```json
{
  "name": "dotnet",
  "version": "0.1.0",
  "description": "Common everyday C#/.NET coding skills. Expected to be useful to all .NET developers.",
  "skills": ["./skills/"],
  "lspServers": "./lsp.json"
}

```

## Skill Definitions in SKILL.md

Individual capabilities are defined within the `skills/` subdirectory. Each skill occupies its own folder containing a [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) file that follows the Agent Skills specification with YAML front-matter.

For example, [`plugins/dotnet/skills/dotnet-pinvoke/SKILL.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet/skills/dotnet-pinvoke/SKILL.md) contains:

```markdown
---
name: dotnet-pinvoke
description: |
  Correctly call native (C/C++) libraries from .NET using P/Invoke and LibraryImport.
license: MIT
---

# .NET P/Invoke

## Inputs

None

## Workflow

1. Analyze the native library signature
2. Generate the C# interop code

```

## Optional Auxiliary Files

While the manifest and skill definitions are required, several optional files enhance functionality:

- **[`README.md`](https://github.com/dotnet/skills/blob/main/README.md)**: Provides human-focused documentation displayed in the marketplace
- **[`lsp.json`](https://github.com/dotnet/skills/blob/main/lsp.json)**: Declares Language Server Protocol support; [`plugins/dotnet/lsp.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet/lsp.json) exposes C# language services

- **`references/`**: Contains supporting documentation referenced from skill files, such as [`plugins/dotnet/skills/dotnet-pinvoke/references/type-mapping.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet/skills/dotnet-pinvoke/references/type-mapping.md)

## Step-by-Step Guide to Structure Plugins in dotnet/skills

Follow this sequence to add a properly structured plugin:

1. Create a folder under `plugins/` with your desired identifier (e.g., `plugins/my-plugin/`)
2. Add [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) at the root with the `"name"` field matching the folder name exactly
3. Create a `skills/` subdirectory to house capability definitions
4. Add skill folders, each containing a [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) with proper YAML front-matter
5. Optionally add [`README.md`](https://github.com/dotnet/skills/blob/main/README.md), [`lsp.json`](https://github.com/dotnet/skills/blob/main/lsp.json), or `references/` directories as needed
6. Commit and push; the CI pipeline validates against [`eng/skill-validator/src/Models.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Models.cs)

## Summary

- Plugins reside under `plugins/<name>/` where the folder name serves as the canonical identifier used by the marketplace
- The [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest is mandatory and must include `name`, `version`, `description`, and `skills` fields
- Skill definitions live in `skills/<skill-name>/SKILL.md` files using YAML front-matter for metadata
- Optional [`lsp.json`](https://github.com/dotnet/skills/blob/main/lsp.json) enables Language Server Protocol integration for IDE features
- The CI pipeline validates all plugins against the schema in [`eng/skill-validator/src/Models.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Models.cs)

## Frequently Asked Questions

### What is the minimum required structure for a dotnet/skills plugin?

The minimal structure requires a directory under `plugins/` containing a [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest. This file must specify `name`, `version`, `description`, and `skills` fields matching the directory name. Additionally, you must include a `skills/` subdirectory containing at least one [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) file with valid YAML front-matter defining the capability.

### How does the runtime validate plugin structure?

The CI pipeline runs a validator located at [`eng/skill-validator/src/Models.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Models.cs) that checks for required manifest fields, valid JSON syntax, and proper [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) formatting. Missing required fields or schema violations cause the build to fail immediately.

### Can a single plugin contain multiple skills?

Yes. A plugin can define multiple capabilities by creating multiple subdirectories under its `skills/` folder, each containing its own [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) file. The core `dotnet` plugin demonstrates this pattern with separate skills for C# scripts and P/Invoke operations within the same plugin container.

### What is the purpose of the lsp.json file?

The [`lsp.json`](https://github.com/dotnet/skills/blob/main/lsp.json) file optionally declares Language Server Protocol server configuration, enabling IDE features like IntelliSense and code navigation for users working with the plugin. The `dotnet` plugin uses this file to expose C# language server capabilities to compatible editors.