Skip to content

Commit 1c42150

Browse files
aaronpowellaaronpowell
authored
Merge pull request #630 from alvinashcraft/alvinashcraft/main-add-skill-winapp-cli
feat: Add Windows App Development (winapp) CLI skill
2 parents e27435c + a11df38 commit 1c42150

2 files changed

Lines changed: 197 additions & 0 deletions

File tree

‎docs/README.skills.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -51,4 +51,5 @@ Skills differ from other primitives by supporting bundled assets (scripts, code
5151
| [vscode-ext-localization](../skills/vscode-ext-localization/SKILL.md) | Guidelines for proper localization of VS Code extensions, following VS Code extension development guidelines, libraries and good practices | None |
5252
| [web-design-reviewer](../skills/web-design-reviewer/SKILL.md) | This skill enables visual inspection of websites running locally or remotely to identify and fix design issues. Triggers on requests like "review website design", "check the UI", "fix the layout", "find design problems". Detects issues with responsive design, accessibility, visual consistency, and layout breakage, then performs fixes at the source code level. | `references/framework-fixes.md`<br />`references/visual-checklist.md` |
5353
| [webapp-testing](../skills/webapp-testing/SKILL.md) | Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs. | `test-helper.js` |
54+
| [winapp-cli](../skills/winapp-cli/SKILL.md) | Windows App Development CLI (winapp) for building, packaging, and deploying Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, generate AppxManifest.xml, manage development certificates, add package identity for debugging, sign packages, or access Windows SDK build tools. Supports .NET, C++, Electron, Rust, Tauri, and cross-platform frameworks targeting Windows. | None |
5455
| [workiq-copilot](../skills/workiq-copilot/SKILL.md) | Guides the Copilot CLI on how to use the WorkIQ CLI/MCP server to query Microsoft 365 Copilot data (emails, meetings, docs, Teams, people) for live context, summaries, and recommendations. | None |

‎skills/winapp-cli/SKILL.md‎

Lines changed: 196 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,196 @@
1+
---
2+
name: winapp-cli
3+
description: 'Windows App Development CLI (winapp) for building, packaging, and deploying Windows applications. Use when asked to initialize Windows app projects, create MSIX packages, generate AppxManifest.xml, manage development certificates, add package identity for debugging, sign packages, or access Windows SDK build tools. Supports .NET, C++, Electron, Rust, Tauri, and cross-platform frameworks targeting Windows.'
4+
---
5+
6+
# Windows App Development CLI
7+
8+
The Windows App Development CLI (`winapp`) is a command-line interface for managing Windows SDKs, MSIX packaging, generating app identity, manifests, certificates, and using build tools with any app framework. It bridges the gap between cross-platform development and Windows-native capabilities.
9+
10+
## When to Use This Skill
11+
12+
Use this skill when you need to:
13+
14+
- Initialize a Windows app project with SDK setup, manifests, and certificates
15+
- Create MSIX packages from application directories
16+
- Generate or manage AppxManifest.xml files
17+
- Create and install development certificates for signing
18+
- Add package identity for debugging Windows APIs
19+
- Sign MSIX packages or executables
20+
- Access Windows SDK build tools from any framework
21+
- Build Windows apps using cross-platform frameworks (Electron, Rust, Tauri, Qt)
22+
- Set up CI/CD pipelines for Windows app deployment
23+
- Access Windows APIs that require package identity (notifications, Windows AI, shell integration)
24+
25+
## Prerequisites
26+
27+
- Windows 10 or later
28+
- winapp CLI installed via one of these methods:
29+
- **WinGet**: `winget install Microsoft.WinAppCli --source winget`
30+
- **NPM** (for Electron): `npm install @microsoft/winappcli --save-dev`
31+
- **GitHub Actions/Azure DevOps**: Use [setup-WinAppCli](https://github.com/microsoft/setup-WinAppCli) action
32+
- **Manual**: Download from [GitHub Releases](https://github.com/microsoft/WinAppCli/releases/latest)
33+
34+
## Core Capabilities
35+
36+
### 1. Project Initialization (`winapp init`)
37+
38+
Initialize a directory with required assets (manifest, certificates, libraries) for building a modern Windows app. Supports SDK installation modes: `stable`, `preview`, `experimental`, or `none`.
39+
40+
### 2. MSIX Packaging (`winapp pack`)
41+
42+
Create MSIX packages from prepared directories with optional signing, certificate generation, and self-contained deployment bundling.
43+
44+
### 3. Package Identity for Debugging (`winapp create-debug-identity`)
45+
46+
Add temporary package identity to executables for debugging Windows APIs that require identity (notifications, Windows AI, shell integration) without full packaging.
47+
48+
### 4. Manifest Management (`winapp manifest`)
49+
50+
Generate AppxManifest.xml files and update image assets from source images, automatically creating all required sizes and aspect ratios.
51+
52+
### 5. Certificate Management (`winapp cert`)
53+
54+
Generate development certificates and install them to the local machine store for signing packages.
55+
56+
### 6. Package Signing (`winapp sign`)
57+
58+
Sign MSIX packages and executables with PFX certificates, with optional timestamp server support.
59+
60+
### 7. SDK Build Tools Access (`winapp tool`)
61+
62+
Run Windows SDK build tools with properly configured paths from any framework or build system.
63+
64+
## Usage Examples
65+
66+
### Example 1: Initialize and Package a Windows App
67+
68+
```bash
69+
# Initialize workspace with defaults
70+
winapp init
71+
72+
# Build your application (framework-specific)
73+
# ...
74+
75+
# Create signed MSIX package
76+
winapp pack ./build-output --generate-cert --output MyApp.msix
77+
```
78+
79+
### Example 2: Debug with Package Identity
80+
81+
```bash
82+
# Add debug identity to executable for testing Windows APIs
83+
winapp create-debug-identity ./bin/MyApp.exe
84+
85+
# Run your app - it now has package identity
86+
./bin/MyApp.exe
87+
```
88+
89+
### Example 3: CI/CD Pipeline Setup
90+
91+
```yaml
92+
# GitHub Actions example
93+
- name: Setup winapp CLI
94+
uses: microsoft/setup-WinAppCli@v1
95+
96+
- name: Initialize and Package
97+
run: |
98+
winapp init --no-prompt
99+
winapp pack ./build-output --output MyApp.msix
100+
```
101+
102+
### Example 4: Electron App Integration
103+
104+
```bash
105+
# Install via npm
106+
npm install @microsoft/winappcli --save-dev
107+
108+
# Initialize and add debug identity for Electron
109+
npx winapp init
110+
npx winapp node add-electron-debug-identity
111+
112+
# Package for distribution
113+
npx winapp pack ./out --output MyElectronApp.msix
114+
```
115+
116+
## Guidelines
117+
118+
1. **Run `winapp init` first** - Always initialize your project before using other commands to ensure SDK setup, manifest, and certificates are configured.
119+
2. **Re-run `create-debug-identity` after manifest changes** - Package identity must be recreated whenever AppxManifest.xml is modified.
120+
3. **Use `--no-prompt` for CI/CD** - Prevents interactive prompts in automated pipelines by using default values.
121+
4. **Use `winapp restore` for shared projects** - Recreates the exact environment state defined in `winapp.yaml` across machines.
122+
5. **Generate assets from a single image** - Use `winapp manifest update-assets` with one logo to generate all required icon sizes.
123+
124+
## Common Patterns
125+
126+
### Pattern: Initialize New Project
127+
128+
```bash
129+
cd my-project
130+
winapp init
131+
# Creates: AppxManifest.xml, development certificate, SDK configuration, winapp.yaml
132+
```
133+
134+
### Pattern: Package with Existing Certificate
135+
136+
```bash
137+
winapp pack ./build-output --cert ./mycert.pfx --cert-password secret --output MyApp.msix
138+
```
139+
140+
### Pattern: Self-Contained Deployment
141+
142+
```bash
143+
# Bundle Windows App SDK runtime with the package
144+
winapp pack ./my-app --self-contained --generate-cert
145+
```
146+
147+
### Pattern: Update Package Versions
148+
149+
```bash
150+
# Update to latest stable SDKs
151+
winapp update
152+
153+
# Or update to preview SDKs
154+
winapp update --setup-sdks preview
155+
```
156+
157+
## Limitations
158+
159+
- Windows 10 or later required (Windows-only CLI)
160+
- Package identity debugging requires re-running `create-debug-identity` after any manifest changes
161+
- Self-contained deployment increases package size by bundling the Windows App SDK runtime
162+
- Development certificates are for testing only; production requires trusted certificates
163+
- Some Windows APIs require specific capability declarations in the manifest
164+
- winapp CLI is in public preview and subject to change
165+
166+
## Windows APIs Enabled by Package Identity
167+
168+
Package identity unlocks access to powerful Windows APIs:
169+
170+
| API Category | Examples |
171+
| ------------ | -------- |
172+
| **Notifications** | Interactive native notifications, notification management |
173+
| **Windows AI** | On-device LLM, text/image AI APIs (Phi Silica, Windows ML) |
174+
| **Shell Integration** | Explorer, Taskbar, Share sheet integration |
175+
| **Protocol Handlers** | Custom URI schemes (`yourapp://`) |
176+
| **Device Access** | Camera, microphone, location (with consent) |
177+
| **Background Tasks** | Run when app is closed |
178+
| **File Associations** | Open file types with your app |
179+
180+
## Troubleshooting
181+
182+
| Issue | Solution |
183+
| ----- | -------- |
184+
| Certificate not trusted | Run `winapp cert install <cert-path>` to install to local machine store |
185+
| Package identity not working | Run `winapp create-debug-identity` after any manifest changes |
186+
| SDK not found | Run `winapp restore` or `winapp update` to ensure SDKs are installed |
187+
| Signing fails | Verify certificate password and ensure cert is not expired |
188+
189+
## References
190+
191+
- [GitHub Repository](https://github.com/microsoft/WinAppCli)
192+
- [Full CLI Documentation](https://github.com/microsoft/WinAppCli/blob/main/docs/usage.md)
193+
- [Sample Applications](https://github.com/microsoft/WinAppCli/tree/main/samples)
194+
- [Windows App SDK](https://learn.microsoft.com/windows/apps/windows-app-sdk/)
195+
- [MSIX Packaging Overview](https://learn.microsoft.com/windows/msix/overview)
196+
- [Package Identity Overview](https://learn.microsoft.com/windows/apps/desktop/modernize/package-identity-overview)

0 commit comments

Comments
 (0)