maui-skills

Guide for making .NET MAUI apps accessible — screen reader support via SemanticProperties, heading levels, AutomationProperties visibility control, programmatic focus and announcements, and platform-specific gotchas for TalkBack, VoiceOver, and Narrator. USE FOR: "add accessibility", "screen reader support", "SemanticProperties", "AutomationProperties", "TalkBack", "VoiceOver", "Narrator", "accessible MAUI", "heading levels", "semantic description", "announce to screen reader", "accessibility audit". DO NOT USE FOR: general UI layout (use maui-collectionview or maui-shell-navigation), animations (use maui-animations), or gestures (use maui-gestures).

.NET MAUI view animations, custom animations, easing functions, rotation, scale, translation, and fade effects. USE FOR: "animate view", "fade in", "fade out", "slide animation", "scale animation", "rotate view", "translate view", "easing function", "custom animation", "animation chaining", "ViewExtensions animation". DO NOT USE FOR: gesture recognition (use maui-gestures), custom drawing (use maui-graphics-drawing), or static layout changes (use maui-data-binding).

.NET MAUI app icon configuration, splash screen setup, SVG to PNG conversion at build time, composed/adaptive icons, and platform-specific icon and splash screen requirements for Android, iOS, Mac Catalyst, and Windows. USE FOR: "app icon", "splash screen", "MauiIcon", "MauiSplashScreen", "adaptive icon", "change app icon", "launch screen", "SVG icon", "foreground tint", "icon resize". DO NOT USE FOR: in-app images or image loading (use maui-performance), theming or colors (use maui-theming), or custom drawing (use maui-graphics-drawing).

.NET MAUI app lifecycle guidance covering the four app states (not running, running, deactivated, stopped), cross-platform Window lifecycle events, backgrounding and resume behaviour, platform-specific lifecycle mapping for Android and iOS/Mac Catalyst, and state-preservation patterns. USE FOR: "app lifecycle", "OnStart", "OnSleep", "OnResume", "backgrounding", "app state", "window lifecycle", "save state on background", "resume app", "deactivated event", "lifecycle events". DO NOT USE FOR: navigation events (use maui-shell-navigation), dependency injection setup (use maui-dependency-injection), or platform APIs (use maui-platform-invoke).

Guide for .NET MAUI apps consuming .NET Aspire-hosted backend services. Covers AppHost configuration, service discovery for mobile clients, HttpClient DI setup, Entra ID authentication with MSAL.NET for calling protected APIs, development workflow (Aspire dashboard + MAUI debugging), Blazor Hybrid considerations, and platform-specific networking for Android emulators and iOS simulators. USE FOR: "MAUI with Aspire", "Aspire service discovery", "AppHost MAUI", "Aspire backend", "MAUI Aspire networking", "mobile Aspire", "Aspire dashboard MAUI". DO NOT USE FOR: standalone REST API calls without Aspire (use maui-rest-api), authentication without Aspire (use maui-authentication), or Aspire-only projects without MAUI.

Add authentication to .NET MAUI apps. Covers WebAuthenticator for generic OAuth 2.0 / social login, and MSAL.NET for Microsoft Entra ID (Azure AD) with broker support (Microsoft Authenticator), token caching, Conditional Access, platform-specific setup (Android, iOS, Windows), DelegatingHandler for bearer token API calls, and Blazor Hybrid integration. USE FOR: "add authentication", "OAuth login", "MSAL.NET", "social login", "WebAuthenticator", "Entra ID MAUI", "Azure AD login", "Google login MAUI", "Apple login MAUI", "token caching", "bearer token", "sign in". DO NOT USE FOR: secure local storage of tokens (use maui-secure-storage), Aspire-specific auth setup (use maui-aspire), or server-side Entra ID provisioning (use entra-id-aspire-provisioning).

Guidance for implementing CollectionView in .NET MAUI apps — data display, layouts (list & grid), selection, grouping, scrolling, empty views, templates, incremental loading, swipe actions, and pull-to-refresh. USE FOR: "CollectionView", "list view", "grid layout", "data template", "item template", "grouping", "pull to refresh", "incremental loading", "swipe actions", "empty view", "selection mode", "scroll to item". DO NOT USE FOR: simple static layouts (use maui-data-binding), map pin lists (use maui-maps), or table-based data entry forms.

Always-on guardrail for .NET MAUI API currency. Prevents AI coding agents from using deprecated, obsolete, or removed APIs across XAML/C#, Blazor Hybrid, and MauiReactor. Includes a reasoning framework for detecting project target framework and library versions, plus a curated table of the most common deprecated API traps in .NET MAUI 10. USE FOR: "deprecated API", "obsolete API", "API migration", "MAUI breaking changes", "check API currency", "review MAUI code", "generate MAUI code", "edit MAUI code". DO NOT USE FOR: learning new MAUI features (use feature-specific skills), performance optimization (use maui-performance), or testing guidance (use maui-unit-testing).

Guide for creating custom .NET MAUI handlers, customizing existing handlers with property mappers, and implementing platform-specific native views. Covers PrependToMapping/ModifyMapping/AppendToMapping, PropertyMapper, CommandMapper, partial handler classes, and handler registration. USE FOR: "custom handler", "PropertyMapper", "AppendToMapping", "PrependToMapping", "ModifyMapping", "CommandMapper", "platform-specific rendering", "native view", "handler registration", "custom control renderer". DO NOT USE FOR: platform API calls without custom controls (use maui-platform-invoke), data binding (use maui-data-binding), or gesture handling (use maui-gestures).

Guidance for .NET MAUI XAML data bindings, compiled bindings, value converters, binding modes, multi-binding, relative bindings, and MVVM best practices. USE FOR: "data binding", "compiled binding", "value converter", "IValueConverter", "binding mode", "TwoWay binding", "multi-binding", "relative binding", "BindingContext", "MVVM binding", "INotifyPropertyChanged". DO NOT USE FOR: CollectionView item templates (use maui-collectionview), Shell navigation data passing (use maui-shell-navigation), or dependency injection (use maui-dependency-injection).

Guide for implementing deep linking in .NET MAUI apps. Covers Android App Links with intent filters, Digital Asset Links, and AutoVerify; iOS Universal Links with Associated Domains entitlements and Apple App Site Association files; custom URI schemes; and domain verification for both platforms. USE FOR: "deep linking", "app links", "universal links", "custom URI scheme", "intent filter", "Associated Domains", "Digital Asset Links", "open app from URL", "handle incoming URL", "domain verification". DO NOT USE FOR: in-app Shell navigation (use maui-shell-navigation), push notification handling (use maui-push-notifications), or web content embedding (use maui-hybridwebview).

Guidance for dependency injection in .NET MAUI apps — service registration, lifetime selection (Singleton/Transient/Scoped), constructor injection, automatic resolution via Shell navigation, explicit resolution patterns, platform-specific registrations, and testability best practices. USE FOR: "dependency injection", "DI registration", "AddSingleton", "AddTransient", "AddScoped", "service registration", "constructor injection", "IServiceProvider", "MauiProgram DI", "register services". DO NOT USE FOR: data binding (use maui-data-binding), Shell route setup (use maui-shell-navigation), or unit test mocking patterns (use maui-unit-testing).

Guidance for file picker, file system helpers, bundled assets, and app data storage in .NET MAUI applications. Covers FilePicker APIs, FileResult handling, platform permissions, and common pitfalls across Android, iOS, macOS, and Windows. USE FOR: "file picker", "FilePicker", "pick file", "open file", "save file", "bundled assets", "FileSystem helpers", "AppDataDirectory", "CacheDirectory", "FileResult", "read file MAUI". DO NOT USE FOR: media capture or photo picking (use maui-media-picker), secure credential storage (use maui-secure-storage), or SQLite database files (use maui-sqlite-database).

Add geolocation capabilities to .NET MAUI apps using Microsoft.Maui.Devices.Sensors. Covers one-shot and continuous location, platform permissions (Android, iOS, macOS, Windows), accuracy levels, CancellationToken usage, mock-location detection, and a DI-friendly service wrapper. USE FOR: "geolocation", "GPS location", "get current location", "location permission", "continuous location", "location tracking", "GeolocationRequest", "mock location", "latitude longitude MAUI". DO NOT USE FOR: displaying locations on a map (use maui-maps), general permission handling (use maui-permissions), or geocoding addresses (use maui-maps).

Guidance for implementing tap, swipe, pan, pinch, drag-and-drop, and pointer gesture recognizers in .NET MAUI applications. Covers XAML and C# usage, combining gestures, and platform differences. USE FOR: "tap gesture", "swipe gesture", "pan gesture", "pinch gesture", "drag and drop", "pointer gesture", "gesture recognizer", "TapGestureRecognizer", "SwipeGestureRecognizer", "PanGestureRecognizer", "combine gestures". DO NOT USE FOR: animations triggered by gestures (use maui-animations), CollectionView swipe actions (use maui-collectionview), or custom drawing interaction (use maui-graphics-drawing).

Guidance for custom drawing with Microsoft.Maui.Graphics, GraphicsView, canvas drawing operations, shapes, paths, text rendering, image drawing, shadows, clipping, and canvas state management. USE FOR: "custom drawing", "GraphicsView", "canvas drawing", "draw shapes", "draw path", "draw text", "ICanvas", "IDrawable", "shadows", "clipping", "Microsoft.Maui.Graphics". DO NOT USE FOR: view animations (use maui-animations), gesture handling on drawn elements (use maui-gestures), or app icons (use maui-app-icons-splash).

Diagnose and troubleshoot .NET MAUI Hot Reload issues (C# Hot Reload, XAML Hot Reload, Blazor Hybrid). Covers all UI approaches (XAML, MauiReactor, C# Markup, Blazor Hybrid), Visual Studio, VS Code, environment variables, encoding requirements, and MetadataUpdateHandler. USE FOR: "hot reload not working", "XAML hot reload", "C# hot reload", "UI not updating", "hot reload troubleshooting", "MetadataUpdateHandler", "hot reload Blazor Hybrid", "hot reload VS Code", "DOTNET_WATCH". DO NOT USE FOR: general build errors (not hot reload related), app lifecycle events (use maui-app-lifecycle), or performance profiling (use maui-performance).

Guidance for embedding web content in .NET MAUI apps using HybridWebView, including JavaScript–C# interop, bidirectional communication, raw messaging, and trimming/NativeAOT considerations. USE FOR: "HybridWebView", "JavaScript interop", "embed web content", "JS to C# interop", "C# to JavaScript", "web view interop", "raw message", "InvokeJavaScriptAsync", "web content MAUI". DO NOT USE FOR: deep linking from external URLs (use maui-deep-linking), REST API calls (use maui-rest-api), or Blazor Hybrid apps (different from HybridWebView).

Add local notifications to .NET MAUI apps on Android, iOS, and Mac Catalyst. Covers notification channels, permissions, scheduling, foreground/background handling, and DI registration. Works with XAML/MVVM, C# Markup, and MauiReactor. USE FOR: "local notification", "schedule notification", "notification channel", "notification permission", "reminder notification", "alert notification", "in-app notification", "foreground notification". DO NOT USE FOR: push notifications from a server (use maui-push-notifications), permission handling only (use maui-permissions), or app lifecycle background tasks (use maui-app-lifecycle).

Guidance for localizing .NET MAUI apps: multi-language support via .resx resource files, culture resolution and runtime switching, RTL layout, platform language declarations (iOS/Mac Catalyst Info.plist, Windows Package.appxmanifest), and image localization strategies. USE FOR: "localization", "multi-language", "resx resource", "translate app", "RTL layout", "culture switching", "localize strings", "right-to-left", "language support MAUI", "Info.plist languages". DO NOT USE FOR: theming or visual styles (use maui-theming), accessibility labels (use maui-accessibility), or content from REST APIs (use maui-rest-api).

Guidance for adding map controls, pins, polygons, polylines, geocoding, Google Maps API key configuration, and platform setup in .NET MAUI apps using Microsoft.Maui.Controls.Maps. USE FOR: "add map", "map control", "map pins", "polygons on map", "polylines", "geocoding", "Google Maps API key", "Microsoft.Maui.Controls.Maps", "map setup", "reverse geocoding", "map region". DO NOT USE FOR: getting device GPS coordinates (use maui-geolocation), custom drawing overlays (use maui-graphics-drawing), or location permissions only (use maui-permissions).

Guidance for picking photos/videos, capturing from camera, multi-select (.NET 10), MediaPickerOptions, platform permissions, and FileResult handling in .NET MAUI. USE FOR: "pick photo", "capture photo", "take picture", "pick video", "camera capture", "MediaPicker", "photo gallery", "image picker", "multi-select photos", "MediaPickerOptions". DO NOT USE FOR: general file picking (use maui-file-handling), image display or optimization (use maui-performance), or camera streaming (use maui-platform-invoke).

Performance optimization guidance for .NET MAUI apps covering profiling, compiled bindings, layout efficiency, image optimization, resource dictionaries, startup time, trimming, and NativeAOT configuration. USE FOR: "performance optimization", "slow startup", "app performance", "compiled bindings", "layout optimization", "image optimization", "trimming", "NativeAOT", "profiling MAUI", "reduce app size", "startup time". DO NOT USE FOR: data binding syntax (use maui-data-binding), deprecated API migration (use maui-current-apis), or unit testing setup (use maui-unit-testing).

.NET MAUI runtime permissions guidance — checking and requesting permissions, PermissionStatus handling, custom permissions via BasePlatformPermission, platform-specific manifest/plist declarations, and DI-friendly service patterns. USE FOR: "request permission", "check permission", "PermissionStatus", "runtime permission", "BasePlatformPermission", "custom permission", "Android manifest permission", "Info.plist permission", "permission denied handling". DO NOT USE FOR: geolocation-specific permissions (use maui-geolocation), camera/photo permissions (use maui-media-picker), or notification permissions (use maui-local-notifications).

Guidance for calling platform-specific native APIs from .NET MAUI apps. Covers partial classes, conditional compilation, multi-targeting configuration, and dependency injection patterns for cross-platform code that needs Android, iOS, Mac Catalyst, or Windows functionality. USE FOR: "platform-specific code", "conditional compilation", "partial class", "#if ANDROID", "#if IOS", "multi-targeting", "native API call", "platform invoke", "platform-specific DI", "DeviceInfo.Platform". DO NOT USE FOR: custom control handlers (use maui-custom-handlers), permission requests (use maui-permissions), or dependency injection patterns (use maui-dependency-injection).

End-to-end guide for adding push notifications to .NET MAUI apps. Covers Firebase Cloud Messaging (Android), Apple Push Notification Service (iOS), Azure Notification Hubs as the cross-platform broker, an ASP.NET Core backend API, and the MAUI client wiring on every platform. USE FOR: "push notification", "FCM", "APNS", "Firebase Cloud Messaging", "Azure Notification Hubs", "device registration", "remote notification", "send push notification", "notification token". DO NOT USE FOR: local/scheduled notifications (use maui-local-notifications), general permission handling (use maui-permissions), or background tasks without notifications (use maui-app-lifecycle).

Guidance for consuming REST APIs in .NET MAUI apps. Covers HttpClient setup with System.Text.Json, DI registration, service interface/implementation pattern, full CRUD operations (GET, POST, PUT, DELETE), error handling, platform-specific clear-text traffic configuration, and async/await best practices. USE FOR: "REST API", "HttpClient", "call API", "GET request", "POST request", "API service", "JSON deserialization", "CRUD operations", "clear-text traffic", "consume API MAUI". DO NOT USE FOR: Aspire service discovery (use maui-aspire), authentication token handling (use maui-authentication), or local database storage (use maui-sqlite-database).

.NET MAUI safe area and edge-to-edge layout guidance for .NET 10+. Covers SafeAreaEdges property, SafeAreaRegions enum, per-edge control, keyboard avoidance, Blazor Hybrid CSS safe areas, migration from legacy APIs, and platform-specific behavior for Android, iOS, and Mac Catalyst. USE FOR: "safe area", "edge-to-edge", "SafeAreaEdges", "SafeAreaRegions", "keyboard avoidance", "notch insets", "status bar overlap", "iOS safe area", "Android edge-to-edge", "content behind status bar". DO NOT USE FOR: general layout or grid design (use maui-collectionview), app lifecycle handling (use maui-app-lifecycle), or theming (use maui-theming).

Add secure storage to .NET MAUI apps using SecureStorage.Default. Covers SetAsync, GetAsync, Remove, RemoveAll, platform setup (Android backup rules, iOS Keychain entitlements, Windows limits), common pitfalls, and a DI wrapper service for testability. USE FOR: "secure storage", "SecureStorage", "store token securely", "Keychain", "Android Keystore", "save secret", "encrypted storage", "store credentials", "sensitive data storage". DO NOT USE FOR: general file storage (use maui-file-handling), SQLite databases (use maui-sqlite-database), or authentication flows (use maui-authentication).

.NET MAUI Shell navigation guidance — Shell visual hierarchy, AppShell setup, tab bars, flyout menus, URI-based navigation with GoToAsync, route registration, query parameters, back navigation, and navigation events. USE FOR: "Shell navigation", "GoToAsync", "AppShell", "tab bar", "flyout menu", "route registration", "query parameters navigation", "back navigation", "Shell tabs", "URI navigation", "navigation events". DO NOT USE FOR: deep linking from external URLs (use maui-deep-linking), data binding on pages (use maui-data-binding), or dependency injection setup (use maui-dependency-injection).

Add speech-to-text voice input to .NET MAUI apps using CommunityToolkit.Maui. Covers speech recognition, microphone permissions, and hands-free text entry. Works with any UI pattern (XAML/MVVM, C# Markup, MauiReactor). USE FOR: "speech to text", "voice input", "speech recognition", "microphone input", "voice command", "dictation", "SpeechToText", "hands-free text", "transcribe speech". DO NOT USE FOR: text-to-speech output (different feature), media playback (use maui-media-picker), or general permissions (use maui-permissions).

Add SQLite local database storage to .NET MAUI apps using sqlite-net-pcl. Covers data models with ORM attributes, async database service with lazy init, DI registration, WAL mode, and file management. Works with any UI pattern (XAML/MVVM, C# Markup, MauiReactor). USE FOR: "SQLite database", "local database", "sqlite-net-pcl", "offline storage", "CRUD database", "database service", "WAL mode", "CreateTableAsync", "local data persistence", "ORM attributes". DO NOT USE FOR: REST API data fetching (use maui-rest-api), secure credential storage (use maui-secure-storage), or file picking (use maui-file-handling).

Guide for theming .NET MAUI apps—light/dark mode support, AppThemeBinding, dynamic resources, ResourceDictionary theme switching, and system theme detection. USE FOR: "dark mode", "light mode", "theming", "AppThemeBinding", "theme switching", "ResourceDictionary theme", "dynamic resources", "system theme detection", "color scheme", "app theme". DO NOT USE FOR: localization or language switching (use maui-localization), accessibility visual adjustments (use maui-accessibility), or app icons (use maui-app-icons-splash).

xUnit testing guidance for .NET MAUI apps — ViewModel testing, mocking MAUI services, test project setup, code coverage, and on-device test runners. USE FOR: "unit test MAUI", "xUnit test", "ViewModel testing", "mock MAUI services", "test project setup", "code coverage", "on-device test runner", "test MAUI app", "IServiceProvider mock", "Moq MAUI". DO NOT USE FOR: UI automation testing (use appium-automation), performance profiling (use maui-performance), or dependency injection setup (use maui-dependency-injection).

**WORKFLOW SKILL** - Guide for migrating Xamarin.Android native apps to .NET for Android. Covers SDK-style project conversion, target framework monikers, MSBuild property changes, AndroidManifest.xml updates, NuGet dependency compatibility, Android binding library migration, Xamarin.Essentials in native apps, .NET CLI support, and platform-specific gotchas. USE FOR: "migrate Xamarin.Android", "upgrade Xamarin.Android to .NET", "Xamarin.Android to .NET for Android", "Android project migration", "Android binding library migration", "convert Android project to SDK-style", "AndroidSupportedAbis to RuntimeIdentifiers". DO NOT USE FOR: migrating Xamarin.Forms apps (use xamarin-forms-migration), migrating Xamarin.iOS apps (use xamarin-ios-migration), creating new MAUI apps from scratch (use feature-specific MAUI skills).

**WORKFLOW SKILL** - Guide for migrating Xamarin.Forms apps to .NET MAUI. Covers project structure decisions, SDK-style project conversion, namespace renames, layout behavior changes, renderer-to-handler migration, effects-to-behaviors redesign, Xamarin.Essentials namespace mapping, NuGet dependency compatibility, data migration, and common troubleshooting. Incorporates field-tested advice from production migrations. USE FOR: "migrate Xamarin.Forms", "upgrade to MAUI", "Xamarin to MAUI", "convert Xamarin.Forms project", "Forms migration", "namespace changes Xamarin", "renderer to handler", "effects to behaviors", "AndExpand replacement", "layout changes MAUI", "Xamarin.Essentials to MAUI". DO NOT USE FOR: migrating Xamarin.Android native apps (use xamarin-android-migration), migrating Xamarin.iOS native apps (use xamarin-ios-migration), creating new MAUI handlers from scratch (use maui-custom-handlers), performance optimization (use maui-performance).

**WORKFLOW SKILL** - Guide for migrating Xamarin.iOS, Xamarin.Mac, and Xamarin.tvOS native apps to .NET for iOS, .NET for macOS, and .NET for tvOS. Covers SDK-style project conversion, target framework monikers, MSBuild property changes, Info.plist updates, iOS binding library migration, Xamarin.Essentials in native apps, NuGet dependency compatibility, and code signing changes. USE FOR: "migrate Xamarin.iOS", "upgrade Xamarin.iOS to .NET", "Xamarin.iOS to .NET for iOS", "iOS project migration", "Xamarin.Mac migration", "tvOS migration", "iOS binding library migration", "MtouchArch to RuntimeIdentifier", "Apple project migration". DO NOT USE FOR: migrating Xamarin.Forms apps (use xamarin-forms-migration), migrating Xamarin.Android apps (use xamarin-android-migration), creating new MAUI apps from scratch (use feature-specific MAUI skills).