How to Contribute Code Changes to dotnet/skills: A Complete Guide

To contribute code changes to dotnet/skills, fork the repository, create a feature branch, add your skill or agent following the YAML front-matter format, include eval.yaml tests, update CODEOWNERS, and submit a PR targeting the main branch.

The dotnet/skills repository hosts a collection of AI skills and agents built on the .NET ecosystem. Contributing to this repository requires understanding its plugin-based architecture, validation workflows, and specific formatting conventions defined in CONTRIBUTING.md.

Prerequisites and Repository Setup

Before writing code, prepare your local environment to match the repository's requirements.

Fork and Clone the Repository

Start by creating a personal fork on GitHub, then clone it locally:

git clone https://github.com/<your-user>/skills.git
cd skills

Install Required Dependencies

The repository requires a specific .NET SDK version defined in global.json. According to the repository's README.md (lines 27-28), ensure your installed version matches or exceeds the version listed:

dotnet --version

Additionally, authenticate with the GitHub CLI to enable CI pipeline interactions:

gh auth login

Understanding the Repository Structure

The dotnet/skills repository organizes content into discrete plugins, each containing metadata, skills, and optional agents.

Plugin Architecture

Every plugin resides under plugins/<plugin-name>/ and contains:

• plugin.json – Marketplace metadata including name, description, and source
• skills/ – Directory containing individual skill definitions
• agents/ – Optional directory for agent role definitions

Skill Layout

Skills are human-readable instruction sets stored at plugins/<plugin>/skills/<skill-name>/SKILL.md. Each file requires YAML front-matter and structured markdown content.

Test Locations

Validation scenarios live separately under tests/<plugin>/<skill-name>/eval.yaml. These files define assertions that the skill-validator engine runs during CI.

Creating a New Skill or Agent

When adding functionality, first decide whether to extend an existing plugin or create a new one. For new plugins, follow the "Create a new plugin" checklist in CONTRIBUTING.md (lines 49-55).

SKILL.md Format Requirements

Every skill file must begin with YAML front-matter. As specified in CONTRIBUTING.md (lines 31-36), include at minimum:

---
name: add-aspnet-auth
description: Adds ASP.NET Core authentication middleware to a project
---

Following the front-matter, include these sections:

• Purpose – What the skill accomplishes
• When to use – Context for applicability
• Inputs – Required parameters
• Workflow – Step-by-step instructions
• Validation – How to verify success
• Common pitfalls – Known issues to avoid

Keep the body under 500 lines; split large content into supplemental files referenced from the main document.

Agent Definitions

Agents reside at plugins/<plugin>/agents/<agent-name>.agent.md and define role bindings to specific skills.

Adding Test Scenarios

Every skill must ship an eval.yaml file that the skill-validator runs on pull requests. According to CONTRIBUTING.md (lines 10-21), the schema includes:

scenarios:
  - name: "Add ASP.NET auth"
    prompt: "Add authentication to the project"
    assertions:
      - type: output_contains
        value: "Authentication middleware added"
    rubric:
      - "The agent modifies Startup.cs correctly"
      - "The agent updates csproj with required packages"
    timeout: 120

Place this file at tests/<plugin>/<skill-name>/eval.yaml to ensure CI discovers it.

Local Validation and Testing

Before submitting, validate your changes locally using the skill-validator CLI.

Running the Validator

Execute the validator against your skill and test files:

dotnet run --project eng/skill-validator/src/SkillValidator.csproj \
  -- evaluate \
  --tests-dir tests/dotnet/add-aspnet-auth \
  --skill-dir plugins/dotnet/skills/add-aspnet-auth

As noted in CONTRIBUTING.md (line 39), add the --runs flag to increase confidence with multiple validation passes.

Submitting Your Contribution

Branch and Commit

Create a descriptive branch name and commit your changes:

git checkout -b feat/add-aspnet-auth
git add .
git commit -m "feat: add ASP.NET Core authentication skill"
git push origin feat/add-aspnet-auth

Update Code Ownership

Add entries to .github/CODEOWNERS for any new files you create, as required by CONTRIBUTING.md (lines 13-19). This ensures the correct reviewers are automatically assigned.

Open a Pull Request

Target dotnet/skills:main with your PR. The description should reference related issues and summarize what the change does, why it is needed, and validation steps performed, following the guidelines in CONTRIBUTING.md (lines 97-104).

CI Evaluation

When files under plugins/ change, the evaluation workflow (.github/workflows/evaluation.yml) automatically runs the skill-validator against your eval.yaml. Results appear as PR comments with links to results.json for debugging.

Summary

• Fork and clone the repository, ensuring your .NET SDK matches global.json
• Structure content under plugins/<plugin>/skills/ with proper YAML front-matter
• Include tests in tests/<plugin>/<skill>/eval.yaml with assertions and rubrics
• Update CODEOWNERS to assign reviewers for new files
• Validate locally using eng/skill-validator/src/SkillValidator.csproj
• Target main with your PR and respond to CI feedback

Frequently Asked Questions

What is the maximum length for a SKILL.md file?

Keep SKILL.md files under 500 lines. If your skill requires more content, split it into supplemental files and reference them from the main document, as outlined in CONTRIBUTING.md (lines 43-62).

How do I run skill validation before submitting a PR?

Use the skill-validator CLI located at eng/skill-validator/src/SkillValidator.csproj. Run dotnet run --project eng/skill-validator/src/SkillValidator.csproj -- evaluate with --tests-dir and --skill-dir parameters pointing to your files.

What happens if my eval.yaml test fails in CI?

The evaluation workflow (.github/workflows/evaluation.yml) posts results as a PR comment with a link to results.json. You can debug locally using the validator CLI with the same parameters to reproduce failures.

Do I need to update CODEOWNERS for every new skill?

Yes. According to CONTRIBUTING.md (lines 13-19), you must add ownership entries for new plugins, skills, and agents in .github/CODEOWNERS to ensure appropriate reviewers are automatically requested.

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