# How to Contribute Code Changes to dotnet/skills: A Complete Guide > Learn how to contribute code changes to dotnet/skills. Follow our guide to fork, branch, add your skill, test, and submit a pull request to the main branch. - Repository: [.NET Platform/skills](https://github.com/dotnet/skills) - Tags: how-to-guide - Published: 2026-07-08 --- **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`](https://github.com/dotnet/skills/blob/main/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: ```bash git clone https://github.com//skills.git cd skills ``` ### Install Required Dependencies The repository requires a specific .NET SDK version defined in [`global.json`](https://github.com/dotnet/skills/blob/main/global.json). According to the repository's [`README.md`](https://github.com/dotnet/skills/blob/main/README.md) (lines 27-28), ensure your installed version matches or exceeds the version listed: ```bash dotnet --version ``` Additionally, authenticate with the GitHub CLI to enable CI pipeline interactions: ```bash 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//` and contains: - **[`plugin.json`](https://github.com/dotnet/skills/blob/main/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//skills//SKILL.md`. Each file requires YAML front-matter and structured markdown content. ### Test Locations Validation scenarios live separately under `tests///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`](https://github.com/dotnet/skills/blob/main/CONTRIBUTING.md) (lines 49-55). ### SKILL.md Format Requirements Every skill file must begin with YAML front-matter. As specified in [`CONTRIBUTING.md`](https://github.com/dotnet/skills/blob/main/CONTRIBUTING.md) (lines 31-36), include at minimum: ```yaml --- 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//agents/.agent.md` and define role bindings to specific skills. ## Adding Test Scenarios Every skill must ship an [`eval.yaml`](https://github.com/dotnet/skills/blob/main/eval.yaml) file that the skill-validator runs on pull requests. According to [`CONTRIBUTING.md`](https://github.com/dotnet/skills/blob/main/CONTRIBUTING.md) (lines 10-21), the schema includes: ```yaml 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///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: ```bash 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`](https://github.com/dotnet/skills/blob/main/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: ```bash 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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/CONTRIBUTING.md) (lines 97-104). ### CI Evaluation When files under `plugins/` change, the evaluation workflow ([`.github/workflows/evaluation.yml`](https://github.com/dotnet/skills/blob/main/.github/workflows/evaluation.yml)) automatically runs the skill-validator against your [`eval.yaml`](https://github.com/dotnet/skills/blob/main/eval.yaml). Results appear as PR comments with links to [`results.json`](https://github.com/dotnet/skills/blob/main/results.json) for debugging. ## Summary - **Fork and clone** the repository, ensuring your .NET SDK matches [`global.json`](https://github.com/dotnet/skills/blob/main/global.json) - **Structure content** under `plugins//skills/` with proper YAML front-matter - **Include tests** in `tests///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`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/.github/workflows/evaluation.yml)) posts results as a PR comment with a link to [`results.json`](https://github.com/dotnet/skills/blob/main/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`](https://github.com/dotnet/skills/blob/main/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.