aalmada/Stationary / .agents/skills/dotnet-maui
dotnet-maui
VerifiedBuild, architect, debug, test, and publish .NET MAUI 10 cross-platform native apps for Android, iOS, Mac Catalyst, and Windows using C#, XAML, or C# markup. USE FOR: MAUI project configuration, single-project targeting, pages, layouts, controls, XAML, MVVM, data binding, CommunityToolkit.Mvvm, dependency injection, Shell navigation, handlers, platform integration, permissions, lifecycle, accessibility, localization, performance, trimming, Appium UI tests, Android/iOS/Windows publishing. DO NOT USE FOR: ASP.NET Core web UI, Blazor-only apps, Avalonia, WPF-only, Xamarin.Forms migration without MAUI target code, or generic .NET code with no MAUI UI or platform concern.
.NET MAUI
Build one native app project for Android, iOS, Mac Catalyst, and Windows. Start with the target platform and user workflow; share UI and domain code, and isolate platform implementations.
Workflow
- Confirm target frameworks, supported OS versions, signing requirements, and physical-device test coverage.
- Keep views declarative and thin; place presentation state and commands in view models.
- Register services and view models in
MauiProgram.CreateMauiApp; inject dependencies through constructors. - Use Shell with explicit, stable routes for app navigation. Validate and minimize navigation data.
- Put platform-specific implementations behind shared interfaces. Add manifest, entitlement, or permission declarations before invoking device APIs.
- Handle window lifecycle transitions: cancel resource-intensive work on
Stopped, refresh/reconnect onResumed, and dispose native subscriptions onDestroying. - Unit-test view models and services; run Appium UI tests for essential workflows on each target platform.
- Test Release builds on real devices. Verify trimming, signing, store metadata, privacy declarations, and platform package output before publishing.
Quick Reference
| Concern | Use | Avoid |
|---|---|---|
| UI | XAML bindings, compiled bindings where applicable, resource dictionaries | Business logic in code-behind |
| Styling | App-level XAML styles, resources, triggers, and visual states | CSS for stateful or complete app styling |
| Presentation logic | MVVM and commands | Control event handlers as application logic |
| Dependencies | Microsoft.Extensions.DependencyInjection constructor injection | Service locator calls in views/view models |
| Navigation | Shell routes and GoToAsync | Generated routes or duplicate route names |
| Cross-platform APIs | Microsoft.Maui.Essentials abstractions | Direct platform API calls from shared UI |
| Platform variation | Platforms/, partial classes, interfaces, handlers | Scattered #if blocks in domain code |
| Async work | Cancellation tokens and lifecycle-aware refresh | Fire-and-forget work tied to a page |
| Collections | Main-thread mutations | Editing bound ObservableCollection<T> on a worker thread |
Project Shape
| Location | Responsibility |
|---|---|
MauiProgram.cs | App bootstrap, dependency registrations, logging, fonts, handlers |
App.xaml | Global resources and application root |
AppShell.xaml | Root navigation hierarchy and explicit routes |
Views/ | Pages and reusable visual components |
ViewModels/ | Bindable state, commands, validation, presentation coordination |
Services/ | Data access, platform abstractions, external integrations |
Platforms/ | Platform manifest, entitlements, native implementations, lifecycle hooks |
Resources/ | Images, fonts, raw assets, styles, localization resources |
Guardrails
- Do not hold page, view, activity, or native-control references in singleton services.
- Do not assume lifecycle events mean the process will be terminated or resumed; persist necessary state early.
- Treat UI thread affinity as a requirement for collection changes and native control access.
- Do not use
AddScopedas a per-page lifetime unless you explicitly create and dispose scopes; MAUI has no automatic navigation scope. - Request only the permissions needed immediately before the related feature, and handle denial.
- Use semantic properties, accessible names, keyboard paths, and platform accessibility inspectors.
Reference Files
| File | Load When |
|---|---|
| references/architecture-and-startup.md | Structuring a MAUI app, configuring the single project, bootstrapping MauiProgram, DI, logging, configuration, or handlers |
| references/mvvm-bindings-and-ui.md | Building XAML UI, MVVM state/commands, compiled bindings, resources, controls, accessibility, localization, or collection views |
| references/shell-navigation.md | Defining Shell hierarchy/routes, navigating, passing data, deep links, back-stack behavior, or navigation lifecycle events |
| references/platform-integration.md | Accessing device APIs, implementing target-specific behavior, configuring handlers, declaring permissions, or storing secrets |
| references/lifecycle-and-async.md | Responding to window/platform lifecycle events, cancellation, backgrounding, resuming, or resource cleanup |
| references/testing.md | Unit-testing view models/services, adding Appium UI tests, selecting emulators/devices, or validating platform behavior |
| references/performance-and-trimming.md | Diagnosing startup/scrolling/memory issues, virtualizing lists, optimizing resources, or publishing a trimmed app |
| references/deployment-and-publishing.md | Signing, provisioning, packaging, versioning, and distributing Android, iOS, Mac Catalyst, or Windows apps |
| references/best-practices.md | Reviewing cross-cutting architecture, UI, navigation, lifecycle, platform, testing, performance, and release decisions |
| references/sources.md | Rechecking facts against the current official .NET MAUI documentation and samples |
Sources
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |