114 lines
4.7 KiB
Markdown
114 lines
4.7 KiB
Markdown
# 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](README.md) table). `winui` and `winappcli` are
|
|
maintained in [microsoft/winappCli](https://github.com/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](https://github.com/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](https://agent-plugins.org/specification) layout, plus
|
|
the manifests each host needs:
|
|
|
|
```text
|
|
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:
|
|
|
|
1. 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.
|
|
2. Add a `/plugins/<name>/` entry to [`.github/CODEOWNERS`](.github/CODEOWNERS).
|
|
3. 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:
|
|
|
|
```jsonc
|
|
// .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`](.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](https://github.com/microsoft/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):
|
|
|
|
```powershell
|
|
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](CODE_OF_CONDUCT.md).
|
|
|
|
## CLA
|
|
|
|
Contributions of non-trivial size require signing the
|
|
[Microsoft CLA](https://opensource.microsoft.com/cla/). The CLA bot will
|
|
prompt you on your first PR.
|