Winui Dev Workflow Agent Skill

Build and run workflow for WinUI 3 apps — project creation, BuildAndRun.ps1 script, winapp run, error diagnosis, and prerequisites. Use when building, running, or fixing build errors in a WinUI 3 project.

17k tokens

context cost

the whole folder, loaded on every use

files

instructions only

copies elsewhere

how many repositories repackaged it

58 d ago

last touched

this folder, not the whole repository

Install

one command, takes just this skill from the repository

npx skills add https://github.com/microsoft/win-dev-skills --skill winui-dev-workflow

The instruction itself

8 sections, as written by the author

Create or Open a Project

New app — scaffold with a template:

dotnet new winui-mvvm -n <AppName>
cd <AppName>

Creates an MVVM project with CommunityToolkit.Mvvm, TitleBar, MicaBackdrop, and Frame navigation. Do NOT mkdir first — -n creates the folder.

Existing app — read the .csproj to understand:

<TargetFramework> (e.g., net10.0-windows10.0.26100.0)
<PackageReference> versions (WindowsAppSDK, CommunityToolkit)
Project structure and established patterns

Install Packages

dotnet add package <Name>

Never specify --version — omitting it gets the latest stable and avoids outdated API mismatches.

Build & Run

Use the BuildAndRun.ps1 script (included with this skill) — it handles everything:

.\BuildAndRun.ps1

Invoke the script with mode: "async". The script stays attached to the running app so a mode: "sync" call blocks your turn for the entire lifetime of the app. The output contains the PID of the running app once the app starts, which looks like this:

✅ <pkg> launched (PID: 12345)

What the script does automatically:

Checks Developer Mode is enabled (fails fast if not)
Finds the .csproj in the current directory
Auto-detects platform (x64 or ARM64)
Builds with dotnet build (or Visual Studio MSBuild if you pass -UseMSBuild)
Finds the build output folder
Launches with winapp run --debug-output

Options:

.\BuildAndRun.ps1                          # auto-find csproj, build, run (should use async invocation)
.\BuildAndRun.ps1 MyApp.csproj             # explicit project
.\BuildAndRun.ps1 -Detach                  # run in detached mode, no debug output or exceptions (safe to use mode: "sync")
.\BuildAndRun.ps1 -SkipRun                 # build only (safe to use mode: "sync")
.\BuildAndRun.ps1 -Symbols                 # build + run, adding --symbols (optional Symbol Server fallback)
.\BuildAndRun.ps1 /p:Configuration=Release # override defaults

If build fails: Read ALL errors, batch-fix them in one pass, then run BuildAndRun.ps1 again.

If the app crashes on launch: read_powershell the shell — first-chance exceptions appear in the output. See the crash-diagnosis section below for WinUI stowed-exception triage.

Diagnosing Crashes with `winapp run`

For WinUI apps, --debug-output (the BuildAndRun.ps1 default) runs a stowed-exception triage on crash, surfacing the real WinUI/XAML error behind an opaque 0x8000FFFF / E_FAIL — plus a fully symbolicated native dispatch stack (symbols auto-download, so --debug-output alone is enough). The first crash also downloads debugger components and can take a few minutes — it looks like a hang but it's caching; point WINAPP_DBGTOOLS_DIR at an existing *Debugging Tools for Windows* install to skip it. Later runs use the cache.

Common Errors

| Error | Fix |

|-------|-----|

| Developer Mode not enabled | Settings → System → For developers → On |

| CS0234/CS0246 missing type | Add using or dotnet add package |

| NETSDK1136 platform required | BuildAndRun.ps1 handles this automatically |

| XLS0414 XAML type not found | Add xmlns declaration |

| XDG0062 binding path missing | Check x:Bind property exists on ViewModel |

| Blank window after launch | x:Bind defaults to OneTime — add Mode=OneWay |

| App silently exits | Use winapp run, never run the .exe directly |

| App crashes with opaque 0x8000FFFF / E_FAIL | Run under --debug-output (BuildAndRun.ps1 default) — WinUI stowed-exception triage surfaces the real XAML error + symbolicated native stack. -Symbols optional, not required |

| XAML compiler crashes silently | Remove any PresentationCore.dll / System.Windows references |

| MSB3073 / XamlCompiler.exe ... exited with code 1, no .xaml named | Old WindowsAppSDK XAML-compiler bug — update Microsoft.WindowsAppSDK NuGet to latest (≥ 2.1.3, or ≥ 1.8 on the 1.x line) |

| 0x80073CF6 package install failed | Run winapp init, check manifest publisher matches cert |

| 0x8007000B bad image format | Wrong platform target — use x64 or ARM64, not AnyCPU |

Prerequisites

|-------------|---------|------------------------------|-----------------|

| Windows 10 v1903+ | — | — | — |

| .NET SDK | 8.0 | 10.0 | winget install Microsoft.DotNet.SDK.10 |

If any of these are missing when you try to access them — winapp or dotnet not recognized, the WinUI templates aren't installed, Developer Mode is off — do not try to install them yourself and do not try to work around it. Stop and tell the user the prerequisite is missing and ask them to run /winui-setup (a user-invoked skill that installs and verifies everything). Once they've finished, retry the failed command.

Critical Rules

❌ NEVER run the packaged .exe directly — always use winapp run or BuildAndRun.ps1
❌ NEVER add <WindowsPackageType>None to work around launch issues
❌ NEVER delete Package.appxmanifest
❌ NEVER use AnyCPU — always x64 or ARM64

References

BuildAndRun.ps1 — included with this skill, handles build + run automatically

Other skills for the same job

different authors, same section of the catalogue

Doc Coauthoring

by anthropics

vendor ×10

Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

Intelligently organizes your files and folders across your computer by understanding context, finding duplicates, suggesting better structures, and automating cleanup tasks. Reduces cognitive load and keeps your digital workspace tidy without manual effort.

3k tokens

Domain Name Brainstormer

by frostant

×8

Generates creative domain name ideas for your project and checks availability across multiple TLDs (.com, .io, .dev, .ai, etc.). Saves hours of brainstorming and manual checking.

You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.

Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.

9k tokens scripts

Scientific Brainstorming

by christophacham

×3

Creative research ideation and exploration. Use for open-ended brainstorming sessions, exploring interdisciplinary connections, challenging assumptions, or identifying research gaps. Best for early-stage research planning when you do not have specific observations yet. For formulating testable hypotheses from data use hypothesis-generation.

5k tokens

GitHub Project Management

by ComeOnOliver

×3

Comprehensive GitHub project management with swarm-coordinated issue tracking, project board automation, and sprint planning

Interview the user relentlessly about a plan or design until reaching shared understanding, resolving each branch of the decision tree. Use when user wants to stress-test a plan, get grilled on their design, or mentions "grill me".