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

To contribute a new plugin to dotnet/skills, create a dedicated folder under plugins/, define a plugin.json manifest, register the component in .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 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 files and scripts
• plugins/<plugin>/agents/ — Optional role-based agents
• tests/<plugin>/ — Test fixtures including eval.yaml files
• .github/plugin/marketplace.json — Marketplace registration for Copilot, Claude, and Cursor
• .github/CODEOWNERS — Reviewer assignments
• 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:

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.

{
  "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 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 to make your plugin available in the Copilot, Claude, and Cursor marketplaces. Insert a new entry in the plugins array:

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

View the existing list in .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 (around lines 11–25) and append a new row:

Plugin	Description
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 structure:

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:

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, 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 entry
• Updated .github/CODEOWNERS lines
• Updated 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 manifest and skills/ directory containing SKILL.md files.
• Register the plugin in .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 "What's Included" table.
• Test thoroughly by creating 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 manifest in plugins/<plugin>/, at least one skill folder containing a SKILL.md file, an entry in .github/plugin/marketplace.json, and corresponding lines in .github/CODEOWNERS. The 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 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. 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.

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