Contributing to `win-dev-skills`

This repo hosts agent plugins for Windows development and debugging under plugins/<name>/, and also lists plugins maintained in other repos, pinned to a release. You can contribute:

A new plugin. Add it here (Option A), or pin a plugin from its own repo (Option B).
Skills for an existing plugin. Send them to wherever that plugin is maintained (see the README table). winui and winappcli are maintained in microsoft/winappCli; file their issues and PRs there.

Bar for inclusion

Windows development and debugging. Building, designing, testing, debugging, packaging, or shipping Windows apps, services, or kernel-mode drivers.
Small and curated. A focused plugin with a few skills that each do one job well, not a dump of prompts.
Clear descriptions. Each skill description is 300 characters or fewer and says when to use it and when not to: "Use when… Not for…".
No overlap. Check existing plugins first: winappcli and winui in this catalog, and dotnet/skills' dotnet-diag, dotnet-winforms, and dotnet-maui. Extend one of those instead of duplicating it.
Owned. Two or more maintainers who review its PRs.

Open an issue first if you're unsure whether a plugin fits.

Option A: add a plugin here

Use the Agent Plugins layout, plus the manifests each host needs:

plugins/<name>/
  plugin.json                  Agent Plugins manifest with "$schema" (Copilot, Codex)
  .claude-plugin/plugin.json   Claude Code manifest (same name and version)
  skills/<skill>/SKILL.md      one folder per skill
  com.github.copilot/agents/   optional Copilot agents

Then:

Add the plugin to all three catalogs. Use "source": "./plugins/<name>" in .github/plugin/marketplace.json and .claude-plugin/marketplace.json, and "source": { "source": "local", "path": "./plugins/<name>" } in .agents/plugins/marketplace.json. Use the same name, and the same version as the manifests.
Add a /plugins/<name>/ entry to .github/CODEOWNERS.
Add a row to the README plugin table (the only place plugins are listed; list the hosts it supports) and a CHANGELOG.md entry.

Option B: pin a plugin from another repo

Use this when the plugin ships with a product in its own repo. Pin a release tag and its commit sha in all three catalogs:

// .github/plugin/marketplace.json
"source": { "source": "github", "repo": "owner/repo", "path": "plugins/<name>", "ref": "v1.2.3", "sha": "<40-char sha>" }
// .claude-plugin/marketplace.json and .agents/plugins/marketplace.json
"source": { "source": "git-subdir", "url": "https://github.com/owner/repo.git", "path": "plugins/<name>", "ref": "v1.2.3", "sha": "<40-char sha>" }

Resolve the sha with gh api repos/<owner>/<repo>/commits/<tag> --jq .sha. Add the README table row and a CHANGELOG.md entry. The source repo owns the plugin's content, issues, and PRs.

Bumping a pin

Open a PR that updates ref, sha, and the plugin version in all three catalogs. Hosts only pick up new content when the version changes. CI checks that the tag still points at the sha, and that the version matches the plugin's manifests at that commit.

Review

.github/CODEOWNERS routes catalog, CI, and tooling changes to the catalog maintainers, and plugins/<name>/ changes to that plugin's owners. PRs target main.

CI checks

Check	What it wants
`Catalog check`	Every entry resolves: repo, commit, path, and the host's plugin manifest exist, and its name and version match. A `ref` must resolve to the pinned `sha`. All three catalogs list the same plugins at the same pin.
`Local plugin lint (vally)`	Plugins in this repo pass the vally lint that awesome-copilot runs. A fixture test proves the check and lint handle a local plugin.

Run them locally (Node 22+; set GITHUB_TOKEN to avoid API rate limits):

node scripts/check-catalogs.mjs
npm ci --prefix scripts/vally
node scripts/vally/lint-skills.mjs
node scripts/tests/test-catalog-tools.mjs

The checks read files only. Before merging, install from your branch on each host (for example copilot plugin marketplace add microsoft/win-dev-skills#<branch>) and confirm the skills load.

Code of Conduct

This project follows the Microsoft Open Source Code of Conduct.

CLA

Contributions of non-trivial size require signing the Microsoft CLA. The CLA bot will prompt you on your first PR.

4.7 KiB Raw Blame History

Contributing to win-dev-skills