A GitHub Copilot, Claude Code, and OpenAI Codex plugin for building native Windows apps with WinUI 3 and the Windows App SDK to cover the end-to-end inner loop: scaffold → design → build → run → test → package → ship.
Warning
🚧 Preview · v0.x — expect breaking changes. Skill names, on-disk layout, agent configuration, analyzer rule IDs, and CLI tool surfaces are all subject to change without notice. There is no SemVer commitment until v1.0. If you need a stable pin, install from a release tag instead of the rolling marketplace (see Pinning to a release). Outputs are suggestions, not authoritative answers — review them before committing or shipping anything they produce.
The plugin requires GitHub Copilot (winget install GitHub.Copilot), Claude Code, or OpenAI Codex installed.
Git (winget install Git.Git) is required for installing pluggins.
Paste this prompt into a Copilot CLI session. It installs the plugin and sets up every prerequisite in one shot:
Install the Copilot CLI plugin "winui" from microsoft/win-dev-skills, then set up my machine for WinUI 3 development. Specifically:
1. Run: copilot plugin marketplace add microsoft/win-dev-skills
2. Run: copilot plugin install winui@win-dev-skills
3. Make sure these prerequisites are present (check first; .NET only installs if missing, but WinApp CLI and templates always upgrade to latest):
- .NET SDK >= 8.0 (run `dotnet --list-sdks`; if none >= 8.0, `winget install --id Microsoft.DotNet.SDK.10 --exact --silent --accept-package-agreements --accept-source-agreements`)
- WinApp CLI: must be >= 0.3 (parse `winapp --version`); if missing or older, `winget install --id Microsoft.WinAppCLI`. THEN regardless run `winget upgrade --id Microsoft.WinAppCLI` to get the latest.
- WinUI 3 templates: always run `dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates` (after refreshing $env:Path) — it upgrades in place if already installed.
- Developer Mode (DWORD HKLM:\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock\AllowDevelopmentWithoutDevLicense == 1) — ASK ME first before triggering UAC; if I decline, just print the elevated command for me to run later.
4. Print a short summary of what was installed vs already present, then tell me to start a new Copilot CLI, activate the "winui-dev" agent, and to ask it to build an app.
If you'd rather run the plugin commands by hand:
GitHub Copilot CLI
The plugin is listed on awesome-copilot and can be installed directly:
copilot plugin install winui@awesome-copilotOr add this repo as a marketplace and install from there:
copilot plugin marketplace add microsoft/win-dev-skills
copilot plugin install winui@win-dev-skillsClaude Code
claude plugin marketplace add microsoft/win-dev-skills
claude plugin install winui@win-dev-skillsOpenAI Codex
Add the microsoft/win-dev-skills marketplace, then enable the winui plugin from the plugin directory.
Note: Codex doesn't have an "agents" concept, so the orchestrator agent isn't exposed there. The skills still work - invoke them by name (e.g.
/winui-setup,/winui-design) and Codex will load them on demand.
Then start a new session and run the winui-setup skill with /winui-setup.
Once setup is done, try a real task:
"Build me a WinUI 3 markdown editor with live preview and a custom title bar"
| Tool | Minimum | Recommended | Install command |
|---|---|---|---|
| Git | 2.54 | 2.54+ | winget install Git.Git |
| .NET SDK | 8.0 | 10.0 | winget install Microsoft.DotNet.SDK.10 |
| WinApp CLI | 0.3 | latest | winget install Microsoft.WinAppCLI |
| WinUI 3 templates | — | latest | dotnet new install Microsoft.WindowsAppSDK.WinUI.CSharp.Templates |
| Developer Mode | enabled | enabled | DWORD AllowDevelopmentWithoutDevLicense set to 1 |
Visual Studio with the WinUI workload is optional but recommended for the XAML-diagnostics workaround called out in the next section. Neither setup path will install it; if you want it, run:
winget install Microsoft.VisualStudio.Community --override "--add Microsoft.VisualStudio.Workload.Universal"Important
For best results, install Visual Studio with the WinUI workload. There is a known XAML-compiler issue under dotnet build where a malformed XAML file produces no useful diagnostic — the build just fails with no indication of what's wrong in which .xaml. Agents that hit this thrash through unrelated guesses. The winui-dev-workflow skill works around it via a small BuildAndRun.ps1 helper that prefers MSBuild when it's available on the machine and falls back to dotnet build otherwise. This workaround is explicitly temporary and goes away when the next Windows App SDK release fixes the underlying compiler.
Modern Windows app development covers a lot of ground — XAML and Fluent Design, MVVM, MSIX packaging, code signing, Store submission, accessibility, theming, UI automation. AI agents working from generic web context tend to mix WinUI 3 with older stacks (UWP, WPF), miss the packaged-execution model, or stop short of running and verifying what they built. These skills stay in the WinUI 3 lane end-to-end — from dotnet new through a signed MSIX — and pair the agent with tools that give it real, ground-truth answers instead of guesses.
The result: you ask copilot -p "create a WinUI 3 photo viewer with thumbnails and EXIF metadata", and the agent picks the right template, scaffolds the project, designs the XAML with theming and accessibility in mind, wires up MVVM correctly, builds, fixes errors with real diagnostics, launches through the right packaged-execution pipeline, and (if you ask) drives the running app through UI automation to validate it works.
.github/plugin/ Marketplace manifest (marketplace.json)
plugins/winui/ Copilot CLI plugin manifest + agent + skill files
agents/winui-dev/ The orchestrator agent
skills/ The eight skills (see table below)
src/tools/ Source for the in-repo tools shipped with the skills
winmd-cli/ Native-AOT WinRT/.NET metadata indexer (winmd.exe)
winui-search/ Native-AOT search over WinUI Gallery + Toolkit (winui-search.exe)
winui-analyzer/ Microsoft.WindowsAppSDK.Analyzers Roslyn analyzer
scripts/ Helper scripts (see scripts/build-tools.ps1)
A focused agent for WinUI 3 / Windows App SDK / XAML / C# work. Use it for new apps, adding features, converting from WPF/Electron/web, or fixing bugs. It pulls in the skills below as needed.
Each skill is a focused, self-contained playbook. The agent loads winui-design and winui-dev-workflow by default — those cover most "build me a WinUI 3 app" requests end-to-end. You opt into the others when you want them, including winui-setup for one-time machine prep.
| Skill | What it does |
|---|---|
winui-dev-workflow |
Build and run workflow — project creation from templates, the BuildAndRun.ps1 helper, winapp run, error diagnosis, prerequisites. Use when building, running, or fixing build errors. |
winui-design |
UI design and XAML correctness — layout planning, control selection, Fluent Design, theming (Light/Dark/HighContrast), typography, spacing, brushes, accessibility, data-binding review. Bundles winui-search.exe for grounded control lookup against the WinUI Gallery + Community Toolkit catalogue. |
winui-code-review |
Code-quality review before committing — MVVM compliance, x:Bind correctness, accessibility, theming, security, performance. Catches what the compiler and UI tests won't. |
winui-ui-testing |
Automated UI testing — generates a batch test script, runs all tests in one pass, reads results. Covers element assertions, interactions, value checks (TextBox, ComboBox, ToggleSwitch), file pickers, flyouts, dialogs, persistence, accessibility audits. |
winui-packaging |
MSIX packaging, code signing, and distribution — release builds, certificate generation (winapp cert generate), trust, signing (winapp sign), self-contained deployment, GitHub Actions CI/CD, and Microsoft Store submission. |
winui-wpf-migration |
WPF → WinUI 3 migration — namespace replacement, control mapping (DataGrid → ListView, WrapPanel → ItemsRepeater, TabControl → TabView), Dispatcher → DispatcherQueue, System.Drawing → BitmapImage, MVVM conversion to CommunityToolkit.Mvvm, DynamicResource → ThemeResource. |
winui-session-report |
Diagnostic report on the current or a recent Copilot session. Use when filing a bug, debugging agent behaviour, or reviewing what happened during a build session. |
winui-setup |
Install and verify machine prerequisites — .NET SDK 10, the WinApp CLI, the WinUI 3 .NET templates, and Developer Mode. Idempotent. User-invoked only — run it explicitly with /winui-setup to set up a fresh machine; the agent will not load it on its own and will instead ask you to run it if a later command fails because a prerequisite is missing. |
Skills are prompts plus playbooks. They get their actual leverage from a small set of tools — some external, some included in this repo.
winappCLI (winget install Microsoft.WinAppCLI) — the command-line driver for installing, running, signing, packaging, and automating WinUI 3 / WinAppSDK apps. Withoutwinapp, these skills wouldn't be possible. Packaged WinUI 3 apps can't just be launched as a.exe— they need to be installed and started through the right activation pipeline.winapp rundoes exactly that and streams the app's debug output back to the agent so it can see crashes and exceptions instead of staring at silence.winapp uipowers the entirewinui-ui-testingskill: enumerating elements, asserting state, driving controls, capturing accessibility audits — all from the command line, all scriptable, all readable by an AI agent.winapp manifestandwinapp packare what makeswinui-packagingable to take a build all the way to a signed MSIX.winappis being built in parallel with these skills, in lockstep — every time a skill needed a new automation surface or a tighter feedback loop, that requirement landed inwinappfirst.Microsoft.WindowsAppSDK.WinUI.CSharp.Templates— the newdotnet newtemplates for WinUI 3 + Windows App SDK. The dev-workflow skill uses these as the canonical scaffold so every new project starts from the same supported baseline.
Several skills ship helper binaries and PowerShell scripts that run under your user account. None of them are code-signed today. They live in this repo so you can read the source, build them yourself, and verify what they do — that's an explicit launch-preview trade-off, not a long-term distribution model.
| Artifact | Source | What it does | Long-term plan |
|---|---|---|---|
Microsoft.WindowsAppSDK.Analyzers.dll (Roslyn analyzer) |
src/tools/winui-analyzer/ |
Catches common WinUI 3 / WinAppSDK pitfalls at build time: UWP namespace leaks, Window.Current, CoreDispatcher, WebView2 without EnsureCoreWebView2Async, raw TabView content, attached-property syntax bugs, removed ONNX GenAI APIs, the old field-backed [ObservableProperty] pattern, and more. Every rule ships at Warning severity (no Errors) and includes a helpLinkUri. Verified against source on every PR by the analyzer-provenance CI job. |
Publish as the Microsoft.WindowsAppSDK.Analyzers NuGet package; skill stops shipping the prebuilt DLL and projects pick it up via <PackageReference>. |
winmd.exe (winmd-cli) |
src/tools/winmd-cli/ |
Native-AOT WinRT/.NET metadata indexer. The agent uses it to verify an API actually exists and has the signature it thinks it does — before writing code that won't compile. Reads .winmd and managed .dll metadata from NuGet, the Windows SDK, and WinAppSDK and returns the same XML doc text Visual Studio IntelliSense uses. |
Publish as a dotnet tool on NuGet, or fold relevant subcommands into winappcli. |
winui-search.exe (winui-search) |
src/tools/winui-search/ |
Native-AOT BM25 search over WinUI Gallery and CommunityToolkit/Windows scenarios. Lets the agent see real shipping samples for a control before writing a single line of XAML. Embedded JSON snapshots ship offline; live refresh via winui-search update. Distributed today as a prebuilt unsigned exe inside the winui-design skill payload, verified on every PR by the winui-search-provenance CI job. |
Same as winmd-cli — dotnet tool, fold into winappcli, or expose over a small MCP server. |
BuildAndRun.ps1 |
plugins/winui/skills/winui-dev-workflow/BuildAndRun.ps1 |
Picks MSBuild over dotnet build to work around the XAML-compiler diagnostic gap called out above. After a successful build it hands off to winapp run. |
Removed entirely once the next Windows App SDK release fixes the XAML compiler under dotnet build — the skills will switch to dotnet build / dotnet run directly. |
Analyze-Session.ps1 |
plugins/winui/skills/winui-session-report/Analyze-Session.ps1 |
Reads your local Copilot session events and produces a session-report.md for bug filing. The report can include excerpts of your prompts, file paths, and command output — review it before sharing. The skill prints a privacy notice when it runs. |
Fold into the copilot CLI as a session-report subcommand, or publish as a dotnet tool. |
If any of this is a deal-breaker for your environment, please open an issue — that feedback is what determines how quickly each item moves out of "preview, ships from repo" into "signed package on a registry".
# Build all three tools (AOT-publishes winmd-cli and winui-search), run the
# analyzer test suite, and refresh both committed payloads (analyzer DLL inside
# winui-dev-workflow, winui-search.exe inside winui-design). This is the same
# build the pr-validation workflow runs in CI.
./scripts/build-tools.ps1Per-tool READMEs cover what they do and how to consume them in more detail:
src/tools/winui-analyzer/README.md— analyzer + rule catalogsrc/tools/winmd-cli/README.md—winmdCLI usagesrc/tools/winui-search/README.md—winui-searchCLI usage
The default install (copilot plugin install winui@win-dev-skills) tracks
main HEAD — every promotion to main is a tagged release, but the
marketplace install path always picks up the latest. If you need a stable
pin, install from the git URL with a tag ref instead:
copilot plugin install https://github.com/microsoft/win-dev-skills.git#v0.3.0claude plugin install https://github.com/microsoft/win-dev-skills.git#v0.3.0Browse available tags at https://github.com/microsoft/win-dev-skills/tags.
Day-to-day work lands on a staging branch via PRs. Periodically a maintainer
opens a promotion PR (staging → main) that bumps the version and
updates CHANGELOG.md; merging that PR auto-creates a vX.Y.Z git tag at
the merge commit. See CONTRIBUTING.md for the
contributor flow and RELEASING.md for the maintainer
playbook.
Today the plugin targets GitHub Copilot CLI, but we want these skills to be usable from any AI coding host that's a good fit for Windows desktop development. We're actively figuring out the cleanest way to ship for multiple hosts without forking the content — and we want feedback on which hosts matter most to you. File an issue if you have a preference.
After trying the skills, run the winui-session-report skill. It analyzes your session — turns, tokens, build patterns, what worked, what didn't — and produces a session-report.md file. The file may contain excerpts of your prompts, file paths, and command output, so review it before sharing. Please attach it when you open an issue — the bug template asks for it.
If a skill produces something wrong, surprising, or just not as good as it should be, we want to know. Skill names, scopes, structure, distribution mechanics for the analyzer and CLI tools, the BuildAndRun.ps1 workaround — everything you see today is a starting point, and feedback in the next few months shapes where each piece lands.
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA); see opensource.microsoft.com/cla for details. This project has adopted the Microsoft Open Source Code of Conduct. For support channels see SUPPORT.md, and for responsible disclosure of security issues see SECURITY.md.
Open PRs against staging, not main. See CONTRIBUTING.md for the branch model and the release flow.
When you open a PR, the pr-validation workflow rebuilds the analyzer DLL, runs the analyzer test suite, validates the plugin manifest and skill frontmatter, and verifies the committed analyzer binary matches its source. The release-policy workflow additionally enforces the staging/main split (no version bumps in feature PRs; required version bump + CHANGELOG entry in promotion PRs). Run scripts/build-tools.ps1 locally before pushing to keep those checks green.
This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos is subject to those third parties' policies.
This project is licensed under the MIT License. Third-party components and their licenses are listed in THIRD_PARTY_NOTICES.md.