# How to Contribute a New Plugin to dotnet/skills: A Step-by-Step Guide

> Learn how to contribute a new plugin to dotnet/skills. Follow this step-by-step guide to create a plugin, register it, and submit a pull request for review.

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

---

**To contribute a new plugin to dotnet/skills, create a dedicated folder under `plugins/`, define a [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest, register the component in [`.github/plugin/marketplace.json`](https://github.com/dotnet/skills/blob/main/.github/plugin/marketplace.json), assign reviewers via `.github/CODEOWNERS`, update the root README, write validation tests, and submit a pull request for review.**

Contributing a new plugin to the dotnet/skills repository follows a standardized workflow that ensures every component is discoverable, properly owned, and thoroughly tested. This guide walks through the exact files you must modify and the commands you must run, based on the repository's official [`CONTRIBUTING.md`](https://github.com/dotnet/skills/blob/main/CONTRIBUTING.md) and source structure.

## Understand the Repository Layout

Before writing code, familiarize yourself with the directory structure. The repository organizes plugins under `plugins/<plugin-name>/`, with each plugin containing a manifest, skills, and optional agents.

The critical paths are:

- `plugins/<plugin>/plugin.json` — Plugin manifest defining metadata and skill locations
- `plugins/<plugin>/skills/` — Individual skill folders containing [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) files and scripts
- `plugins/<plugin>/agents/` — Optional role-based agents
- `tests/<plugin>/` — Test fixtures including [`eval.yaml`](https://github.com/dotnet/skills/blob/main/eval.yaml) files
- [`.github/plugin/marketplace.json`](https://github.com/dotnet/skills/blob/main/.github/plugin/marketplace.json) — Marketplace registration for Copilot, Claude, and Cursor
- `.github/CODEOWNERS` — Reviewer assignments
- [`README.md`](https://github.com/dotnet/skills/blob/main/README.md) — Plugin listing table (lines 11–25)

## Create the Plugin Folder

Start by adding a new directory under `plugins/` with your desired plugin name, such as `plugins/my-awesome-plugin/`.

### Initialize the Directory Structure

Create the following minimum structure:

```bash
plugins/my-awesome-plugin/
├── plugin.json
└── skills/
    └── my-skill/
        └── SKILL.md

```

### Define the Plugin Manifest

Create **plugin.json** in the plugin root. This file declares the plugin identity and skill locations.

```json
{
  "name": "my-awesome-plugin",
  "version": "0.1.0",
  "description": "A set of skills for …",
  "skills": ["./skills/"]
}

```

Reference an existing manifest such as [`plugins/dotnet/plugin.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet/plugin.json) for a complete example.

### Add Skills and Optional Agents

Inside `skills/`, create subfolders for each skill. Every skill must contain a **SKILL.md** file with required front-matter including `name` and `description`. If your plugin requires role-based agents, add an `agents/` folder at the plugin root.

## Register the Plugin in the Marketplace

Edit [`.github/plugin/marketplace.json`](https://github.com/dotnet/skills/blob/main/.github/plugin/marketplace.json) to make your plugin available in the Copilot, Claude, and Cursor marketplaces. Insert a new entry in the `plugins` array:

```json
{
  "name": "my-awesome-plugin",
  "source": "./plugins/my-awesome-plugin",
  "description": "Skills for …"
}

```

View the existing list in [`.github/plugin/marketplace.json`](https://github.com/dotnet/skills/blob/main/.github/plugin/marketplace.json) to ensure your entry follows the same format.

## Assign Code Ownership

Update `.github/CODEOWNERS` to assign automatic reviewers for your new code. Add lines mapping your plugin and test directories to GitHub teams or individual users:

```

/plugins/my-awesome-plugin/ @yourteam @anotherreviewer
/tests/my-awesome-plugin/ @yourteam @anotherreviewer

```

Check the current owners in `.github/CODEOWNERS` for the exact syntax used in this repository.

## Update the Root Documentation

Locate the **"What's Included"** table in the root [`README.md`](https://github.com/dotnet/skills/blob/main/README.md) (around lines 11–25) and append a new row:

| Plugin | Description |
|--------|-------------|
| [my-awesome-plugin](plugins/my-awesome-plugin/) | Short description of what the plugin provides. |

This ensures users browsing the repository can discover your contribution immediately.

## Write Tests for Your Skills

Create a matching test directory under `tests/my-awesome-plugin/<skill-name>/` and add an **eval.yaml** file. This file defines validation scenarios, prompts, and assertions.

Here is a minimal [`eval.yaml`](https://github.com/dotnet/skills/blob/main/eval.yaml) structure:

```yaml
scenarios:
  - name: "Basic usage"
    prompt: "Show how to …"
    assertions:
      - type: "output_contains"
        value: "expected result"
    rubric:
      - "The skill explains the steps clearly"
      - "The output matches the expected result"
    timeout: 120

```

Run the skill validator locally to verify your tests pass:

```bash
dotnet run --project eng/skill-validator/src/SkillValidator.csproj -- evaluate --tests-dir tests/my-awesome-plugin plugins/my-awesome-plugin/skills/<skill-name>

```

According to [`CONTRIBUTING.md`](https://github.com/dotnet/skills/blob/main/CONTRIBUTING.md), ensure the validator runs at least three times (`--runs 3`) to obtain stable results before submitting.

## Submit Your Pull Request

Prepare a focused pull request that includes:

- The new plugin folder under `plugins/`
- Updated [`.github/plugin/marketplace.json`](https://github.com/dotnet/skills/blob/main/.github/plugin/marketplace.json) entry
- Updated `.github/CODEOWNERS` lines
- Updated [`README.md`](https://github.com/dotnet/skills/blob/main/README.md) table row
- Test fixtures under `tests/`

The CI pipeline automatically invokes the skill-validator for any changed plugins. Ensure all checks pass before requesting review.

Once submitted, the reviewers defined in `CODEOWNERS` are automatically assigned. Address any feedback, and merge once the CI passes and approval is granted.

## Summary

- **Create** a folder under `plugins/<plugin-name>/` with a [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest and `skills/` directory containing [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) files.
- **Register** the plugin in [`.github/plugin/marketplace.json`](https://github.com/dotnet/skills/blob/main/.github/plugin/marketplace.json) to appear in AI assistant marketplaces.
- **Own** your code by adding paths to `.github/CODEOWNERS`.
- **Document** the plugin in the root [`README.md`](https://github.com/dotnet/skills/blob/main/README.md) "What's Included" table.
- **Test** thoroughly by creating [`eval.yaml`](https://github.com/dotnet/skills/blob/main/eval.yaml) files under `tests/<plugin>/` and running the skill validator with `--runs 3`.
- **Submit** a complete PR including all registry updates and test fixtures.

## Frequently Asked Questions

### What files are required to create a new plugin in dotnet/skills?

At minimum, you need a [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest in `plugins/<plugin>/`, at least one skill folder containing a [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) file, an entry in [`.github/plugin/marketplace.json`](https://github.com/dotnet/skills/blob/main/.github/plugin/marketplace.json), and corresponding lines in `.github/CODEOWNERS`. The [`README.md`](https://github.com/dotnet/skills/blob/main/README.md) must also be updated to list the new plugin.

### How do I test my plugin locally before submitting a PR?

Create an [`eval.yaml`](https://github.com/dotnet/skills/blob/main/eval.yaml) file under `tests/<plugin>/<skill-name>/` defining scenarios and assertions. Then run the skill validator using `dotnet run --project eng/skill-validator/src/SkillValidator.csproj -- evaluate --tests-dir tests/<plugin> plugins/<plugin>/skills/<skill-name>`. Run it at least three times to ensure stable results.

### Where do I register my plugin for the AI assistant marketplaces?

Registration happens in [`.github/plugin/marketplace.json`](https://github.com/dotnet/skills/blob/main/.github/plugin/marketplace.json). Add a JSON object to the `plugins` array with `name`, `source` (relative path like `./plugins/my-plugin`), and a short `description`. This file controls visibility in Copilot, Claude, and Cursor marketplaces.

### Who will review my plugin contribution?

Reviewers are automatically assigned based on the `.github/CODEOWNERS` file. You must add lines mapping your plugin path and test path to specific GitHub teams or users (e.g., `/plugins/my-plugin/ @myteam`). These individuals will be notified when you open your pull request.