# How to Manage Plugin Configurations in dotnet/skills

> Learn to manage plugin configurations in dotnet/skills using JSON manifest files validation schemas and runtime values for efficient skill development.

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

---

**Plugin configurations in dotnet/skills are managed through JSON manifest files ([`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json)) that define validation schemas, user-supplied [`config.json`](https://github.com/dotnet/skills/blob/main/config.json) files that provide runtime values, and [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) documentation files that explain usage.**

The dotnet/skills repository organizes automation capabilities as discrete skill plugins under the `plugins/` directory. Managing plugin configurations effectively requires understanding the relationship between machine-readable manifests, human-readable documentation, and runtime configuration files. This guide covers the complete workflow for configuring, validating, and extending plugins in the dotnet/skills ecosystem.

## Understanding the Plugin Configuration Architecture

Each plugin in dotnet/skills is a self-contained unit managed through three primary artifacts:

- **[`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json)** — The machine-readable manifest located at `plugins/<category>/plugin.json` that defines the plugin's name, version, author, entry point, and a JSON schema for configuration parameters.
- **[`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md)** — Human-readable documentation located at `plugins/<category>/skills/<skill-name>/SKILL.md` that explains the skill's purpose, usage, and the meaning of each configuration option.
- **`references/*.md`** — Optional supplemental technical articles located in `plugins/<category>/skills/<skill-name>/references/` that provide migration guides or API documentation.

## Locating Plugin Configuration Files

The repository groups plugins by category under the top-level `plugins/` directory. Each category contains a single [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) that applies to all skills within that category.

```text
plugins/
 ├─ dotnet-upgrade/
 │   ├─ plugin.json            ← manifest for all upgrade skills
 │   └─ skills/
 │       ├─ migrate-nullable-references/
 │       │   ├─ SKILL.md
 │       │   └─ references/
 │       └─ migrate-dotnet9-to-dotnet10/
 │           ├─ SKILL.md
 │           └─ references/
 ├─ dotnet-test/
 │   └─ plugin.json
 └─ dotnet-nuget/
     └─ plugin.json

```

Key files for plugin configuration management include:
- [`plugins/dotnet-upgrade/plugin.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-upgrade/plugin.json) — Manifest and configuration schema for all .NET-upgrade skills.
- [`plugins/dotnet-test/plugin.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-test/plugin.json) — Manifest for test-related skills.
- [`plugins/dotnet-nuget/plugin.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-nuget/plugin.json) — Manifest for NuGet-conversion skills.
- [`plugins/dotnet-upgrade/skills/migrate-nullable-references/SKILL.md`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-upgrade/skills/migrate-nullable-references/SKILL.md) — Configuration guidance for the nullable-reference migration skill.

## Understanding the plugin.json Schema

The [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) file defines the configuration contract that the Skill Validator framework uses to validate user inputs. Here is the schema structure found in [`plugins/dotnet-upgrade/plugin.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-upgrade/plugin.json):

```json
{
  "name": "dotnet-upgrade",
  "description": "Skills that help upgrade .NET projects.",
  "author": "dotnet",
  "version": "1.0.0",
  "entryPoint": "dotnet-upgrade.dll",
  "configuration": {
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "dryRun": {
        "type": "boolean",
        "description": "When true, the skill reports changes without writing files."
      },
      "targetFramework": {
        "type": "string",
        "enum": ["net6.0", "net7.0", "net8.0", "net9.0", "net10.0"],
        "description": "The .NET target framework to upgrade to."
      }
    },
    "required": ["targetFramework"]
  }
}

```

Key fields include:
- **`entryPoint`** — The compiled DLL that the Skill Validator loads at runtime.
- **`configuration`** — A JSON Schema section that validates user-supplied configuration files before execution.

## Supplying Runtime Configuration Files

When invoking a skill, provide a JSON file conforming to the schema defined in the corresponding [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json). The validator loads this file, validates it against the schema, and passes the resulting object to the skill's implementation.

**Example [`config.json`](https://github.com/dotnet/skills/blob/main/config.json) for the Migrate-Nullable-References skill:**

```json
{
  "dryRun": true,
  "targetFramework": "net9.0"
}

```

Pass the configuration file path to the validator's CLI:

```bash
skill-validator run \
  --skill dotnet-upgrade/migrate-nullable-references \
  --config /path/to/config.json

```

If a required property is missing or a value is outside the allowed enum, the validator aborts with a clear error message before executing the skill.

## Configuration Precedence and Environment Overrides

Some plugins expose environment-variable fallbacks for CI/CD pipelines. The configuration precedence order is:

1. **Explicit JSON configuration** — Highest priority, values from the `--config` file.
2. **Environment variables** — Used only when the JSON key is omitted (e.g., `DOTNET_UPGRADE_TARGET`).
3. **Hard-coded defaults** — Defined in the skill's source code.

This design allows pipelines to inject sensitive values without checking them into version control.

## Extending Plugin Configuration Schemas

To add new configuration options to an existing plugin:

1. Open the relevant [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) file (e.g., [`plugins/dotnet-upgrade/plugin.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-upgrade/plugin.json)).
2. Add a new entry under `configuration.properties` following JSON Schema conventions.
3. If the option is required, add the property name to the `configuration.required` array.
4. Update the skill's implementation code to read the new property from the injected configuration object.
5. Refresh the [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) documentation to explain the new flag and provide examples.

Because the schema is validated upfront, any mismatch between the definition and runtime usage is caught before skill execution.

## Best Practices for Plugin Configuration

Follow these recommendations when managing plugin configurations in dotnet/skills:

- **Keep the schema minimal** — Only expose options that users need to tweak. This reduces cognitive load and prevents configuration drift.
- **Document every property** in [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) with a short example to guarantee discoverability.
- **Version the plugin** in the `version` field whenever the schema changes. This allows downstream tools to lock to compatible versions.
- **Provide a `dryRun` flag** for all mutating plugins to enable safer adoption in CI/CD pipelines.
- **Use enums** for known sets (e.g., target frameworks) to catch typos early during validation.

## Real-World Configuration Example

To upgrade a solution from .NET 8 to .NET 9 with a dry run to preview changes:

1. **Create a configuration file** named [`upgrade-config.json`](https://github.com/dotnet/skills/blob/main/upgrade-config.json):

   ```json
   {
     "dryRun": true,
     "targetFramework": "net9.0"
   }
   ```

2. **Execute the skill** via the Skill Validator:

   ```bash
   skill-validator run \
     --skill dotnet-upgrade/migrate-dotnet8-to-dotnet9 \
     --config ./upgrade-config.json
   ```

3. **Review the output** — The validator prints a list of files that would be modified without touching the source tree.

4. **Apply the changes** — Remove `"dryRun": true` or set it to `false`, then re-run the command to execute the migration.

## Summary

- Plugin configurations in dotnet/skills rely on **three core artifacts**: the [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) manifest, the [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) documentation, and optional `references/*.md` files.
- The **Skill Validator** loads [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) to validate user-supplied [`config.json`](https://github.com/dotnet/skills/blob/main/config.json) files before runtime execution.
- Configuration values follow a strict precedence: **explicit JSON > environment variables > hard-coded defaults**.
- When extending plugins, update the **JSON Schema** in [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json), modify the skill implementation, and synchronize the [`SKILL.md`](https://github.com/dotnet/skills/blob/main/SKILL.md) documentation.

## Frequently Asked Questions

### Where is the plugin configuration schema defined in dotnet/skills?

The configuration schema is defined in the [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) file located at the root of each plugin category directory (e.g., [`plugins/dotnet-upgrade/plugin.json`](https://github.com/dotnet/skills/blob/main/plugins/dotnet-upgrade/plugin.json)). This file contains a `configuration` property that follows JSON Schema draft-07 specifications to validate runtime inputs.

### How do I provide configuration values when running a skill?

Create a JSON file (commonly named [`config.json`](https://github.com/dotnet/skills/blob/main/config.json)) that conforms to the schema in the plugin's [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json). Pass the path to this file using the `--config` flag when invoking `skill-validator run`. The validator validates the file against the schema before passing the configuration object to the skill.

### Can I use environment variables instead of configuration files?

Yes. Some plugins support environment variable fallbacks (such as `DOTNET_UPGRADE_TARGET`) that are used when a configuration key is omitted from the JSON file. Environment variables have lower precedence than explicit JSON configuration but higher precedence than hard-coded defaults.

### What happens if my configuration file does not match the schema?

The Skill Validator performs upfront validation of the [`config.json`](https://github.com/dotnet/skills/blob/main/config.json) file against the [`plugin.json`](https://github.com/dotnet/skills/blob/main/plugin.json) schema. If a required property is missing, a value is outside an allowed enum, or a type mismatch occurs, the validator aborts execution and displays a clear error message before the skill runs.