Skip to content

aalmada/Stationary / .agents/skills/dotnet-maui

dotnet-maui

Verified

Build, 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

  1. Confirm target frameworks, supported OS versions, signing requirements, and physical-device test coverage.
  2. Keep views declarative and thin; place presentation state and commands in view models.
  3. Register services and view models in MauiProgram.CreateMauiApp; inject dependencies through constructors.
  4. Use Shell with explicit, stable routes for app navigation. Validate and minimize navigation data.
  5. Put platform-specific implementations behind shared interfaces. Add manifest, entitlement, or permission declarations before invoking device APIs.
  6. Handle window lifecycle transitions: cancel resource-intensive work on Stopped, refresh/reconnect on Resumed, and dispose native subscriptions on Destroying.
  7. Unit-test view models and services; run Appium UI tests for essential workflows on each target platform.
  8. Test Release builds on real devices. Verify trimming, signing, store metadata, privacy declarations, and platform package output before publishing.

Quick Reference

ConcernUseAvoid
UIXAML bindings, compiled bindings where applicable, resource dictionariesBusiness logic in code-behind
StylingApp-level XAML styles, resources, triggers, and visual statesCSS for stateful or complete app styling
Presentation logicMVVM and commandsControl event handlers as application logic
DependenciesMicrosoft.Extensions.DependencyInjection constructor injectionService locator calls in views/view models
NavigationShell routes and GoToAsyncGenerated routes or duplicate route names
Cross-platform APIsMicrosoft.Maui.Essentials abstractionsDirect platform API calls from shared UI
Platform variationPlatforms/, partial classes, interfaces, handlersScattered #if blocks in domain code
Async workCancellation tokens and lifecycle-aware refreshFire-and-forget work tied to a page
CollectionsMain-thread mutationsEditing bound ObservableCollection<T> on a worker thread

Project Shape

LocationResponsibility
MauiProgram.csApp bootstrap, dependency registrations, logging, fonts, handlers
App.xamlGlobal resources and application root
AppShell.xamlRoot 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 AddScoped as 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

FileLoad When
references/architecture-and-startup.mdStructuring a MAUI app, configuring the single project, bootstrapping MauiProgram, DI, logging, configuration, or handlers
references/mvvm-bindings-and-ui.mdBuilding XAML UI, MVVM state/commands, compiled bindings, resources, controls, accessibility, localization, or collection views
references/shell-navigation.mdDefining Shell hierarchy/routes, navigating, passing data, deep links, back-stack behavior, or navigation lifecycle events
references/platform-integration.mdAccessing device APIs, implementing target-specific behavior, configuring handlers, declaring permissions, or storing secrets
references/lifecycle-and-async.mdResponding to window/platform lifecycle events, cancellation, backgrounding, resuming, or resource cleanup
references/testing.mdUnit-testing view models/services, adding Appium UI tests, selecting emulators/devices, or validating platform behavior
references/performance-and-trimming.mdDiagnosing startup/scrolling/memory issues, virtualizing lists, optimizing resources, or publishing a trimmed app
references/deployment-and-publishing.mdSigning, provisioning, packaging, versioning, and distributing Android, iOS, Mac Catalyst, or Windows apps
references/best-practices.mdReviewing cross-cutting architecture, UI, navigation, lifecycle, platform, testing, performance, and release decisions
references/sources.mdRechecking facts against the current official .NET MAUI documentation and samples

Sources

finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
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: 197kUpdated Claude CodeCodexVerifiedInstall