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

Plugins in the dotnet/skills repository must use lower-case, hyphen-separated folder names that match the "name" field in their plugin.json file, with skills stored as markdown files under a skills/ directory and agent definitions using the .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, "The folder name (e.g. plugins/dotnet-test/) should match the "name" field in plugin.json." The PluginDiscovery.ParsePluginJson method in eng/skill-validator/src/Shared/PluginDiscovery.cs enforces this by walking up the file tree to locate 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 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 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, typically using the path "./skills/". Each skill is defined in a markdown file named <skill-name>.md or as 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) and must use the .agent.md suffix. For example, code-testing-tester.agent.md and 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 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:

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 configuration:

{
  "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.
• The 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) stored under the path specified by the "skills" property.
• Agent files must use the .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.

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 is optional. However, if you do include agents, they must follow the .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.

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