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

To structure a plugin in dotnet/skills, create a directory under plugins/ containing a plugin.json manifest and a skills/ subdirectory with 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.

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 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 manifest is mandatory at the root, while README.md and lsp.json remain optional but recommended.

The plugin.json Manifest

Every plugin must contain a 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:

{
  "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 file that follows the Agent Skills specification with YAML front-matter.

For example, plugins/dotnet/skills/dotnet-pinvoke/SKILL.md contains:

---
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: Provides human-focused documentation displayed in the marketplace

• lsp.json: Declares Language Server Protocol support; 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

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 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 with proper YAML front-matter
5. Optionally add README.md, lsp.json, or references/ directories as needed
6. Commit and push; the CI pipeline validates against 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 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 enables Language Server Protocol integration for IDE features
• The CI pipeline validates all plugins against the schema in 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 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 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 that checks for required manifest fields, valid JSON syntax, and proper 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 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 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.

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