# File Naming Conventions for Plugins in dotnet/skills: A Complete Guide

> Master dotnet/skills plugin file naming conventions. Learn how to structure folders, name skills, and define agents to organize your plugin effectively for the dotnet/skills repository.

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

---

**Plugins in the dotnet/skills repository must use lower-case, hyphen-separated folder names that match the `"name"` field in their [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) file, with skills stored as markdown files under a `skills/` directory and agent definitions using the [`.agent.md`](https://github.com/dotnet/skills/blob/main/.agent.md) suffix.**

The `dotnet/skills` repository organizes AI capabilities into discrete plugins that follow strict file naming conventions to ensure compatibility with the skill validator. These conventions govern everything from the root folder name to the suffix of agent definition files, ensuring that new plugins integrate seamlessly with the validation infrastructure.

## Plugin Folder Naming Requirements

### Lower-Case and Hyphen-Separated Format

Every plugin must reside in a self-contained folder under the top-level `plugins/` directory. The folder name must be **lower-case** and use **hyphen separators** (kebab-case), such as `dotnet-test`, `dotnet-msbuild`, or `dotnet-upgrade`.

### Matching the plugin.json Name Field

The folder name must exactly match the `"name"` field declared in the plugin's configuration. According to [`CONTRIBUTING.md`](https://github.com/dotnet/skills/blob/main/CONTRIBUTING.md), "The folder name (e.g. `plugins/dotnet-test/`) should match the `"name"` field in [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json)." The `PluginDiscovery.ParsePluginJson` method in [`eng/skill-validator/src/Shared/PluginDiscovery.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Shared/PluginDiscovery.cs) enforces this by walking up the file tree to locate [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) and validating that the directory name corresponds to the `"name"` value.

## Required Plugin Configuration Files

### The plugin.json Metadata File

Each plugin must contain a [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) file at its root (`plugins/<plugin-name>/plugin.json`). This JSON file declares the plugin's identity, version, description, and paths to skills and agents. As documented in the repository's contribution guidelines, this file is mandatory and must be linked from [`marketplace.json`](https://github.com/dotnet/skills/blob/main/marketplace.json) for the plugin to be discoverable by the validator.

## Organizing Skills and Agents

### Skill File Locations and Naming

Skills are stored in sub-folders referenced by the `"skills"` property in [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json), typically using the path `"./skills/"`. Each skill is defined in a markdown file named `<skill-name>.md` or as [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) within its specific sub-folder. The validator resolves these paths using `AgentRunner.ResolveSkillDirectories` and loads all `*.md` files found within the specified directories.

### Agent File Requirements (.agent.md Suffix)

Agent definitions must reside in an `agents/` folder (or any folder listed in the `"agents"` array in [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json)) and must use the **[`.agent.md`](https://github.com/dotnet/skills/blob/main/.agent.md)** suffix. For example, [`code-testing-tester.agent.md`](https://github.com/dotnet/skills/blob/main/code-testing-tester.agent.md) and [`test-migration.agent.md`](https://github.com/dotnet/skills/blob/main/test-migration.agent.md) are valid agent file names. The validator checks the `"agents"` array and verifies each file ends with the required suffix.

## How the Validator Enforces These Rules

The `eng/skill-validator` project contains the [`PluginDiscovery.cs`](https://github.com/dotnet/skills/blob/main/PluginDiscovery.cs) file which implements the discovery logic. The `ParsePluginJson` method validates the plugin name against the directory structure, while the resolution logic ensures skill paths map correctly to the file system. Files in optional sub-folders like `references/` or `scripts/` are ignored by the validator unless explicitly referenced by a skill, allowing flexibility for supplementary materials.

## Complete Directory Structure Example

The following structure illustrates a properly configured plugin following all naming conventions:

```text
plugins/
├── dotnet-test/                ← plugin folder (lower-case, hyphenated)
│   ├── plugin.json             ← must exist; "name": "dotnet-test"
│   ├── skills/                 ← path referenced in plugin.json
│   │   ├── writing-mstest-tests/
│   │   │   └── SKILL.md        ← skill definition
│   │   └── test-tagging/
│   │       └── SKILL.md
│   └── agents/                 ← optional folder for agents
│       ├── code-testing-tester.agent.md
│       └── test-migration.agent.md

```

The corresponding [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) configuration:

```json
{
  "name": "dotnet-test",
  "version": "0.1.0",
  "description": "Skills for running, diagnosing, and migrating .NET tests...",
  "skills": ["./skills/"],
  "agents": [
    "./agents/code-testing-tester.agent.md",
    "./agents/test-migration.agent.md"
  ]
}

```

## Summary

- Plugin folders must use lower-case, hyphen-separated names under `plugins/` that match the `"name"` field in [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json).
- The [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) file must exist at the root of the plugin folder and declare metadata including skills and agent paths.
- Skill files are markdown documents (`*.md` or [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md)) stored under the path specified by the `"skills"` property.
- Agent files must use the [`.agent.md`](https://github.com/dotnet/skills/blob/main/.agent.md) suffix and reside in paths listed in the `"agents"` array.
- The validator enforces these rules via `PluginDiscovery.ParsePluginJson` in [`eng/skill-validator/src/Shared/PluginDiscovery.cs`](https://github.com/dotnet/skills/blob/main/eng/skill-validator/src/Shared/PluginDiscovery.cs).

## Frequently Asked Questions

### What happens if the plugin folder name doesn't match the plugin.json name field?

The skill validator will reject the plugin during the discovery phase. The `ParsePluginJson` method specifically validates that the directory name matches the `"name"` value, preventing mismatched configurations from entering the marketplace.

### Can I use underscores or camelCase in plugin folder names?

No. The repository requires strict **lower-case, hyphen-separated** naming (kebab-case) for all plugin root folders. This standard is enforced by the validator to maintain consistency across the `plugins/` directory and ensure uniform resource identifiers.

### Are agent files required for every plugin?

No. The `"agents"` array in [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) is optional. However, if you do include agents, they must follow the [`.agent.md`](https://github.com/dotnet/skills/blob/main/.agent.md) suffix convention and reside in folders specified in the configuration, or the validator will flag them as errors during the build process.

### Where should helper scripts and reference documents be stored?

Optional sub-folders like `references/` or `scripts/` can be created under a skill's folder structure. These files are not parsed by the validator unless explicitly referenced by a skill definition, allowing you to organize supplementary materials without violating the core naming conventions.