winui-app

winui-app 技能概览

winui-app 是用来做什么的

winui-app 技能可以帮助你快速搭建、构建并排查基于 C# 和 Windows App SDK 的原生 WinUI 3 桌面应用。它最适合那些不满足于泛泛提示的场景：环境是否就绪、项目脚手架怎么搭、shell/navigation 怎么选、UI 模式怎么定，以及构建或启动出问题时怎么实际修复。

谁应该使用它

如果你正在从零开始做一个新的 Windows 桌面应用，想确认当前机器是否支持 WinUI 3，或者在梳理现有应用的结构和 UX，winui-app 都很适合。它尤其适用于依赖现代 Windows UI 行为的 Frontend Development 工作，包括 XAML 控件、窗口管理、主题、可访问性、响应式布局以及部署。

它为什么不一样

这个技能是以决策为导向的，不只是给灵感。它会把你引向真正有用的官方 Microsoft 指南、WinUI Gallery 模式、Windows App SDK 示例和 CommunityToolkit。也正因为如此，当你在意选对方案、避免错误的基础假设、减少包装或启动问题上浪费时间时，winui-app 会更合适。

如何使用 winui-app 技能

安装并启用

使用下面的命令安装 winui-app：
npx skills add openai/skills --skill winui-app

安装后，只要你的任务涉及 WinUI 3 设置、应用创建，或者 Windows-only 桌面 UI 问题，就可以使用这个技能。如果你是在提示词里调用它，直接说明你需要 winui-app usage 帮助，并写清真实目标，比如新应用脚手架、某个控件布局，或者启动失败。

给技能正确的输入

高质量输入应该把应用状态和目标结果说清楚。例如：

• “在我当前 workspace 里创建一个名为 TaskBoard 的新 WinUI 3 应用，并把它做成 packaged。”
• “我现有的 WinUI 应用在加入 navigation 和 theming 后启动失败；帮我排查 build 和 startup 路径。”
• “我需要一个 WinUI 3 应用的 settings page，只有在 WinUI 本身没有对应控件时才用 CommunityToolkit。”

像“帮我修应用”这种弱输入，会迫使技能去猜项目模型、目标平台和失败模式。

先读对的文件

对于 winui-app，先从 SKILL.md 开始，再查看 references/_sections.md，找到最匹配的细分指南。最有用的路径通常是：

• foundation-setup-and-project-selection.md
• foundation-environment-audit-and-remediation.md
• foundation-winui-app-structure.md
• build-run-and-launch-verification.md
• shell-navigation-and-windowing.md

如果你是在选控件或做视觉打磨，也要看：

• controls-layout-and-adaptive-ui.md
• styling-theming-materials-and-icons.md
• accessibility-input-and-localization.md
• community-toolkit-controls-and-helpers.md

按实战工作流推进

使用这个技能时，建议按下面顺序：

1. 先确认任务属于 setup、scaffold、implementation、review，还是 troubleshooting。
2. 如果是新应用或机器环境配置，先做 readiness 检查，再谈设计选择。
3. 尽早确定应用名称，除非明确要覆盖，否则不要用 --force。
4. 在继续添加 UI 打磨之前，先验证项目能 build 并 launch。
5. 利用参考文件把提示词写具体，尤其是 packaged vs unpackaged 的选择，以及 startup 验证。

winui-app 技能常见问题

winui-app 只适合新项目吗？

不是。winui-app 对已有项目同样有用，尤其是在需要重构、排查故障，或者就 WinUI 3 的结构和 UX 决策寻求指导时。它并不局限于全新的 winui-app install 或脚手架流程。

它是必须替代普通提示词吗？

如果你的任务简单而且范围已经很明确，普通提示词就可能够用。只有当工作依赖正确的 Windows 应用设置、启动行为、部署模型，或者一些通用提示词很容易漏掉的 WinUI 特定约定时，才更适合用 winui-app。

它适合新手吗？

适合，只要你能把应用目标说清楚，并接受一个有引导的工作流。只要你提供目标应用名称、是否 packaged，以及最先想让什么功能跑起来，这个技能对新手就会更友好。

什么时候不该用它？

不要把 winui-app 用在非 Windows 前端、跨平台 UI 技术栈，或者任何与 WinUI 3 和 Windows App SDK 无关的任务上。如果你的应用不是 Windows 桌面应用，这个技能并不合适。

如何改进 winui-app 技能

把关键决策说清楚

最好的 winui-app 输出，来自能明确指出难点的提示词：packaged 还是 unpackaged、新脚手架还是恢复、目标平台是什么，或者某个功能应该用内置 WinUI 还是 CommunityToolkit。这样可以减少猜测，让技能给出的建议更可执行。

提供具体的项目上下文

把项目名、当前文件夹、已有内容，以及任何错误信息都写出来。比如：“我有一个 packaged 的 WinUI 3 应用，位于 C:\src\OrdersDesk，build 能成功，但在 splash screen 之后 launch 崩溃。”这比泛泛地问 winui-app guide 要有效得多。

要求验证，不要只要改动

如果你想要更高质量的结果，就让技能在修改后验证 build 和 launch 行为。这个 repository 强调的是客观检查，所以最强的 winui-app for Frontend Development 工作流，应该以一个已确认可运行的应用收尾，而不只是改过的 XAML。

从第一次结果继续迭代

如果第一次回答太宽泛，就把范围收紧，一次只问一个参考路径、一个 UI 面，或者一种失败模式。常见的改进循环包括：

• 先 scaffold，再做 navigation
• 先 navigation，再做 theming
• 先 theming，再做 accessibility
• 先修 build，再做 deployment review

这样可以让 winui-app 始终聚焦真正的阻塞点，而不是把精力分散到无关的 WinUI 问题上。