How to Customize or Extend the Functionality of dotnet/skills: Complete Plugin Guide

You can customize or extend dotnet/skills by creating new plugins, adding skills to existing plugins, or defining agents—all by editing markdown files without compiling code.

The dotnet/skills repository provides Microsoft's plugin-based architecture for AI coding assistants. When you need to customize or extend the functionality of dotnet/skills, you work within a directory structure of markdown files and JSON manifests that requires no code compilation, using the runtime discovery system implemented in eng/skill-validator/src/Program.cs to automatically index new capabilities.

Understanding the Plugin Architecture

The repository organizes functionality through a strict directory convention under the plugins/ folder. Each subdirectory represents a self-contained plugin containing a plugin manifest (plugin.json), optional skills in markdown format, and optional agent specifications.

According to the source code in plugins/dotnet-test/plugin.json, the manifest declares the plugin's metadata, version, and pointers to skill directories. The runtime loads every plugin discovered in the repository, parsing front-matter from SKILL.md files to build a JSON schema that surfaces capabilities via the standard Agentskills protocol.

Three Methods to Customize or Extend dotnet/skills

Create a New Plugin

To add entirely new functionality, create a new directory under plugins/ with a plugin.json manifest. For example, to create a logging plugin:

{
  "name": "dotnet-logging",
  "version": "0.1.0",
  "description": "Skills for configuring logging in .NET applications.",
  "skills": ["./skills/"],
  "agents": []
}

Place this in plugins/dotnet-logging/plugin.json. The repository's CI pipeline automatically picks up this new plugin, publishes it to .agents/plugins/marketplace.json, and makes it available for installation via /plugin install dotnet-logging@dotnet-agent-skills.

Add a Skill to an Existing Plugin

Skills reside in plugins/<plugin>/skills/<skill-name>/SKILL.md as markdown files with YAML front-matter. To extend the dotnet-test plugin with xUnit support, create plugins/dotnet-test/skills/generate-xunit-tests/SKILL.md:

---
name: generate-xunit-tests
description: Generate xUnit test scaffolding from production code.
license: MIT
---

# Generate xUnit Tests

## When to Use

- User wants a fresh xUnit test project for a given source file.

## Inputs

| Input | Required | Description |
|-------|----------|-------------|
| source-code | Yes | C# source file to test |

| project-name | No | Desired test project name |

## Workflow

1. Parse public members in source-code.
2. Create test classes with [Fact] methods.
3. Emit project file referencing xunit packages.

The manifest at plugins/dotnet-test/plugin.json already points to "./skills/", so the CI pipeline automatically includes your new skill without requiring manifest updates.

Define a New Agent

Agents guide how coding assistants invoke skills. Add a new agent by creating a markdown file under plugins/<plugin>/agents/<agent-name>.agent.md. For the logging plugin example, you might create plugins/dotnet-logging/agents/configure-logging.agent.md:

# Configure Logging Agent

You are a .NET logging expert. When the user asks to set up logging:
1. Gather the desired provider (Serilog, NLog, built-in).
2. Ask for the target project file if not supplied.
3. Invoke the configure-logging skill with appropriate inputs.
4. Return modified .csproj and NuGet references.

Add the filename to the agents array in plugin.json, or omit the field to enable auto-discovery depending on your runtime version.

Implementation Examples

Example: Extending the MSTest Plugin

The existing plugins/dotnet-test/skills/writing-mstest-tests/SKILL.md demonstrates the full structure required, including inputs, workflow sections, and example outputs. When you customize this file or add parallel skills in the same directory, you follow the same front-matter pattern shown in the MSTest skill, which declares the skill name, description, and licensing information in the YAML header.

Example: Plugin Manifest Structure

The dotnet-test manifest in plugins/dotnet-test/plugin.json illustrates the relationship between components:

{
  "name": "dotnet-test",
  "version": "1.0.0",
  "skills": ["./skills/"],
  "agents": ["./agents/"]
}

This structure tells the validator in eng/skill-validator/src/Program.cs where to locate skill definitions and agent specifications during the CI evaluation pipeline.

Critical Files in the Repository

When you customize or extend dotnet/skills, these files determine how your changes integrate with the ecosystem:

• README.md (root) – Central hub listing all plugins and installation instructions for Copilot CLI, Claude Code, Cursor, and Codex clients.
• plugins/<plugin>/plugin.json – Defines plugin identity, version, and directory mappings for skills and agents (see plugins/dotnet-test/plugin.json).
• plugins/<plugin>/skills/**/SKILL.md – Contains the actual skill specifications with front-matter, inputs, and workflow descriptions (reference plugins/dotnet-test/skills/writing-mstest-tests/SKILL.md).
• plugins/<plugin>/agents/*.agent.md – Optional agent specifications that shape LLM invocation patterns.
• .agents/plugins/marketplace.json – Auto-generated manifest that makes plugins discoverable by client applications.
• eng/skill-validator/src/Program.cs – Runtime entry point used by CI to validate and index plugin manifests.

Summary

• New Plugins: Create a directory under plugins/, add plugin.json, and populate with skills or agents to extend dotnet/skills with entirely new capabilities.
• New Skills: Add SKILL.md files under plugins/<plugin>/skills/ to customize existing plugins with additional functionality.
• New Agents: Add *.agent.md files under plugins/<plugin>/agents/ to modify how AI assistants invoke your skills.
• No Compilation Required: All customization happens through markdown and JSON files parsed by the CI pipeline and surfaced via the marketplace manifest.

Frequently Asked Questions

Do I need to compile C# code to customize dotnet/skills?

No. According to the repository structure, you customize or extend functionality by editing markdown files and JSON manifests. The runtime parses these plain-text files directly, eliminating the need for code compilation.

How does the runtime discover new plugins I create?

The CI pipeline automatically discovers new plugins by scanning the plugins/ directory. When you push changes, eng/skill-validator/src/Program.cs validates your plugin.json, indexes the skills, and updates .agents/plugins/marketplace.json to make your plugin available to clients like Copilot CLI and Claude Code.

What is the difference between a skill and an agent in dotnet/skills?

A skill (defined in SKILL.md) specifies what the AI can do, including inputs, workflows, and examples. An agent (defined in *.agent.md) specifies how the AI should invoke that skill, providing prompt templates and context management. Skills define capabilities; agents define invocation behavior.

Can I modify existing skills without breaking the plugin?

Yes. Since skills are markdown files, you can edit existing SKILL.md files under plugins/<plugin>/skills/ to refine workflows or update examples. The CI pipeline validates changes against the schema, and updates are automatically published, allowing you to customize dotnet/skills iteratively.

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