How to Manage Plugin Configurations in dotnet/skills

Plugin configurations in dotnet/skills are managed through JSON manifest files (plugin.json) that define validation schemas, user-supplied config.json files that provide runtime values, and 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 — 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 — 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 that applies to all skills within that category.

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 — Manifest and configuration schema for all .NET-upgrade skills.
• plugins/dotnet-test/plugin.json — Manifest for test-related skills.
• plugins/dotnet-nuget/plugin.json — Manifest for NuGet-conversion skills.
• 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 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:

{
  "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. The validator loads this file, validates it against the schema, and passes the resulting object to the skill's implementation.

Example config.json for the Migrate-Nullable-References skill:

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

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

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 file (e.g., 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 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 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:

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

2. Execute the skill via the Skill Validator:

   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 manifest, the SKILL.md documentation, and optional references/*.md files.
• The Skill Validator loads plugin.json to validate user-supplied 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, modify the skill implementation, and synchronize the 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 file located at the root of each plugin category directory (e.g., 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) that conforms to the schema in the plugin's 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 file against the 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.

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