maui-labs

Make .NET MAUI apps accessible with semantic properties, screen reader labels/hints, heading levels, focus, announcements, AutomationProperties, touch targets, and platform checks. USE FOR: accessibility audits, WCAG UI fixes, TalkBack/VoiceOver/Narrator behavior, SemanticProperties.Description/Hint/HeadingLevel, SemanticScreenReader.Announce, SetSemanticFocus, avoiding redundant Label metadata, hiding decorative content with IsInAccessibleTree=false, and CollectionView row semantics. DO NOT USE FOR: general layout, UI automation only, or performance tuning.

Use `Microsoft.Maui.AI.Attributes` to source-generate `Microsoft.Extensions.AI` tools for MAUI apps. USE FOR: `ExportAIFunction`, `AIToolSource`, `AIToolContext`, `Default.Tools`, DI-bound parameters, chat-session scopes, AOT-safe tools, and `IChatClient.UseFunctionInvocation`. DO NOT USE FOR: Essentials.AI chat or embeddings, native bindings, or theory.

Design .NET MAUI architecture around DI, MVVM, compiled bindings, Shell navigation, route registration, query parameters, and testable services. USE FOR: MauiProgram service registration, page/ViewModel wiring, Shell GoToAsync, Routing.RegisterRoute, trim-safe IQueryAttributable vs [QueryProperty] for full trimming/NativeAOT, Uri.EscapeDataString/UnescapeDataString query handling, x:DataType on pages/DataTemplates, AddTransient page lifetimes, and avoiding BuildServiceProvider/service locator patterns. DO NOT USE FOR: project layout, API currency, or runtime debug tools.

Configure .NET MAUI app icons, splash screens, images, fonts, bundled files, app/window lifecycle, background/resume state, and platform asset/lifecycle settings. USE FOR: MauiIcon, MauiSplashScreen, MauiImage, MauiFont, MauiAsset, Resources/Images, Resources/Fonts, Resources/Raw seed JSON, FileSystem.OpenAppPackageFileAsync, Window Created/Stopped/Resumed/Destroying, ConfigureLifecycleEvents, state restore, Xamarin drawable/UIAppFonts migration, and platform asset overrides. DO NOT USE FOR: localization/theme resources, device permissions, or broad project structure.

Connect MAUI apps to Aspire-hosted APIs. USE FOR: `AddServiceDiscovery`, typed `HttpClient`, `https+http://apiservice`, missing AppHost config on devices, Android emulator `10.0.2.2`, iOS simulator `localhost`, physical-device LAN/dev-tunnel fallbacks, dev certs, Bearer handlers, debug-only cleartext. DO NOT USE FOR: offline caching, OAuth callbacks, or server-side Aspire.

Implement .NET MAUI authentication and secure storage flows with WebAuthenticator, MSAL.NET, platform callback URIs, token caches, brokers, SecureStorage, logout cleanup, and Blazor Hybrid auth handoff. USE FOR: login/logout, OAuth/OIDC redirects, Entra ID, CallbackUrl, WebAuthenticatorCallbackActivity, Android intent filters, CFBundleURLTypes, MSAL redirect URI/BrokerRedirectUri, AcquireTokenSilent, RemoveAsync/GetAccountsAsync token cache cleanup, secure token storage, and native-to-Blazor auth state. DO NOT USE FOR: architecture, API retries/offline behavior, or UI debugging.

Build and debug .NET MAUI Blazor Hybrid features with BlazorWebView, HybridWebView, Razor components, static assets, JS/.NET interop, trimming/NativeAOT concerns, and DevFlow CDP route inspection. USE FOR: MAUI apps hosting Razor UI, embedded HTML/JS, choosing BlazorWebView vs HybridWebView, AddMauiBlazorWebView, RootComponent, SendRawMessage/RawMessageReceived, JSON DTO contracts, JsonSerializerContext, wwwroot assets, hybrid auth/data handoff, stale DOM/Razor route debugging, and maui_cdp_webviews/source/evaluate/screenshot/logs. DO NOT USE FOR: pure XAML UI or browser-only apps.

Apply advanced MAUI control guidance. USE FOR: `CollectionView` incremental loading, `RemainingItemsThreshold`, `EmptyView`, `AutomationId`, avoiding `ScrollView` wrappers, `SafeAreaEdges` on .NET 10, `GraphicsView`/`IDrawable`/`Invalidate` hot-path performance, gestures, animations. DO NOT USE FOR: general layout, full accessibility audits, profiling, or handlers.

Keep MAUI guidance on current, target-framework-safe APIs. USE FOR: inspecting `TargetFramework`/TFM, net8 vs net10 choices, `SafeAreaEdges` vs `On<iOS>().SetUseSafeArea`, replacing `Application.Current.MainPage`, Xamarin.Forms namespaces, Shell/window APIs, avoiding .NET 10-only output on older targets. DO NOT USE FOR: workload discovery, runtime inspection, or migration planning.

Implement/migrate MAUI visual handlers. USE FOR: `EntryHandler.Mapper.AppendToMapping`, scoped `BorderlessEntry` type guards, unique mapper keys, repeated mapper callbacks, renderer-to-handler migration, `ConnectHandler`/`DisconnectHandler` cleanup, `PropertyMapper`, `CommandMapper`, custom `ViewHandler`, platform partial handlers, conflicting partial base classes, `CreatePlatformView`, native namespace leaks, `ConfigureMauiHandlers`. DO NOT USE FOR: non-visual platform APIs, full Xamarin migration, native SDK bindings, or backend code.

Implement .NET MAUI device capabilities with platform permissions and declarations. USE FOR: camera/photo/media capture, MediaPicker.IsCaptureSupported, FilePicker.PickAsync durable copies to FileSystem.AppDataDirectory, GeolocationRequest, Permissions.LocationWhenInUse, UseMauiMaps, Android manifest entries, READ_MEDIA_IMAGES/Android 13+ Photo Picker migration, NSCameraUsageDescription/NSLocationWhenInUseUsageDescription, runtime permission requests, denied/cancelled flows, and durable file access. DO NOT USE FOR: notifications, auth, or UI layout.

Adopt `Microsoft.Maui.Essentials.AI` for local/on-device MAUI AI. USE FOR: Apple Intelligence `AppleIntelligenceChatClient` as `IChatClient`, iOS/macOS/Mac Catalyst 26+ checks, fallback UI, `NLEmbeddingGenerator` semantic search, local `UseFunctionInvocation` tools, privacy/offline UX. DO NOT USE FOR: source-generated tools, cloud-only Azure/OpenAI, UI debug, or non-MAUI AI.

Target MAUI Labs desktop backends from MAUI apps. USE FOR: separate Linux GTK4 head projects, `maui-linux-gtk4`, `maui-macos`, or `maui-wpf` templates, net10 desktop setup, `UseMauiAppLinuxGtk4` or related SDK hooks, AppKit instead of Mac Catalyst, and parity planning. DO NOT USE FOR: implementing backends, handlers, or Essentials services.

Implement .NET MAUI localization, runtime culture switching, RTL layout, platform language declarations, AppThemeBinding, DynamicResource theming, and light/dark/system theme switching. USE FOR: RESX/AppResources, DefaultThreadCurrentUICulture, Preferences-backed language choices, culture-aware formatting, FlowDirection, start/end assets, CFBundleLocalizations, AppThemeBinding, DynamicResource instead of StaticResource for live theme tokens, Application.Current.UserAppTheme, and AppTheme.Unspecified. DO NOT USE FOR: general layout, accessibility audits, or icon/splash assets.

Build .NET MAUI networking and offline data features with HttpClient DI, JSON serialization, emulator/simulator networking, debug cleartext exceptions, SQLite persistence, sync boundaries, retries, cancellation, and error handling. USE FOR: typed HttpClient clients, Android emulator 10.0.2.2, iOS simulator localhost, physical-device LAN/dev-tunnel fallback, offline-first screens, SQLiteAsyncConnection/EF Core sync metadata, sync queues, sensitive offline data encryption decisions, retry/backoff, and background batch/chunk sync. DO NOT USE FOR: auth redirects, Aspire service discovery, or UI layout.

Implement .NET MAUI local notifications, push notifications, Firebase/FCM legacy server-key migration to FCM HTTP v1, APNs/Azure Notification Hubs registration, app links, universal links, custom URI schemes, token refresh/sign-in/logout lifecycle, push payload safety, and deep-link troubleshooting. USE FOR: notification permission UX, Android NotificationChannel and POST_NOTIFICATIONS, iOS UNUserNotificationCenter, push token upload, notification tap navigation, assetlinks.json autoVerify, apple-app-site-association, and CFBundleURLTypes. DO NOT USE FOR: OAuth callback-only flows, generic Shell navigation, or picker/location permissions.

Fix measurable .NET MAUI performance issues: accurate startup profiling with `maui profile startup` using Release builds and physical devices, janky CollectionView scrolling, compiled bindings, oversized images, and trim/NativeAOT regressions. USE FOR: Debug/emulator profiling mistakes, Release physical-device startup measurements, CollectionView nested ScrollView issues, x:DataType, shallow templates, MauiImage BaseSize, remote/gallery image thumbnails, 4000px decode memory, IL2026, NoWarn traps, source-generated serializers, DynamicDependency, linker descriptors, publish-build validation, and before/after measurement. DO NOT USE FOR: generic UI bugs, workload discovery, or architecture-only work.

Add native platform APIs through MAUI services/lifecycle hooks. USE FOR: DI wrappers (`IAppReviewService`, `ICameraService`), `Permissions.CheckStatusAsync`/`RequestAsync`, AndroidManifest.xml, Info.plist, entitlements, partial platform files, `ConfigureLifecycleEvents` `AddAndroid`/`AddiOS`/`AddWindows`, services vs handlers vs bindings. DO NOT USE FOR: visual handlers, native SDK bindings, backend.

Configure .NET MAUI single-project structure: app icons and splash screens, resource folders, shared images/fonts/raw assets, app display/build versioning, Central Package Management, and platform metadata files. USE FOR: MauiIcon, MauiSplashScreen, MauiImage, MauiAsset, Resources/Images/Fonts/Raw, EmbeddedResource/Content migration, PackageVersion, versionless PackageReference, Directory.Packages.props, AndroidManifest.xml, Info.plist, Package.appxmanifest, ApplicationDisplayVersion/ApplicationVersion, package IDs/app identifiers guardrails, and rejecting `maui project version` for store versions. DO NOT USE FOR: UI debugging, workload discovery, or MVVM/Shell architecture.

Help .NET MAUI app teams read official .NET/MAUI release notes and turn them into an upgrade plan. USE FOR: deciding whether an app should move to a new release, summarizing breaking changes, Xcode/JDK/Android SDK requirements, global.json updates, pinned workload install/update --version steps, package updates, CI image changes, migration checklists, validation plans, and using dotnet-workload-info for exact live versions. DO NOT USE FOR: authoring MAUI workload release notes, SDK publishing tables, or app-store marketing copy.

Fix .NET MAUI UI layout, state, and automation issues: CollectionView not scrolling, DataTemplate binding problems, command binding back to page view models, Grid/FlexLayout responsive sizing, and binding-driven states. USE FOR: Auto vs Star Grid rows, avoiding ScrollView parents around CollectionView, rejecting HeightRequest fixes, replacing BindableLayout for large lists, stable AutomationIds, x:DataType item templates, RelativeSource AncestorType command bindings, EmptyView/loading/error states, responsive resources, and UI property bindings. DO NOT USE FOR: Shell routes, full accessibility audits, or vendor-specific controls.

Add and improve automated tests for .NET MAUI apps, focusing on ViewModels, services, platform abstractions, and unit/integration/device test boundaries. USE FOR: xUnit projects, ViewModel tests that avoid MauiProgram.CreateMauiApp, fakes/mocks, MAUI injectable platform interfaces such as IGeolocation/IConnectivity/IPreferences/IFileSystem/ISecureStorage instead of static Essentials calls, avoiding PlatformNotSupportedException in test hosts, testing navigation/data services, Microsoft.Maui.Build.AppProjectReference for MAUI app references, and deciding what must run on device. DO NOT USE FOR: UI automation or production profiling.

Plan Xamarin.Forms to .NET MAUI migrations. USE FOR: audits, fresh `dotnet new maui`, `Xamarin.Forms`/`Xamarin.Essentials` namespace updates, `DependencyService` to DI, `MessagingCenter` to WeakReferenceMessenger/events, renderer triage into mapper/custom handler/platform service/slim binding, `MauiProgram`, permissions, parity. DO NOT USE FOR: brand-new MAUI apps, native SDK bindings, backend.

Create Android slim bindings for MAUI/.NET Android. USE FOR: slim Android binding, Kotlin/Java wrappers, build.gradle.kts, Maven, AAR/JAR, AndroidMavenLibrary, AndroidLibrary, @JvmStatic, XA4241/XA4242, Xamarin.AndroidX/Kotlin NuGets. DO NOT USE FOR: iOS/macOS bindings, general MAUI apps, or NuGet packaging.

Automate MAUI app state through DevFlow Actions. USE FOR: `[DevFlowAction]` shortcuts, login, seed data, deep screens. DO NOT USE FOR: arbitrary methods, DI internals, UI MCP tools, connectivity, or build/deploy issues.

Diagnose DevFlow agent connectivity. USE FOR: `maui devflow` connection failures, agent not found, ports, adb forwarding, broker. DO NOT USE FOR: build failures, setup, visual tree, or Blazor CDP.

Discover MAUI workload metadata from live NuGet APIs. USE FOR: workload manifest lookup, WorkloadDependencies.json, v3-flatcontainer, CLI-to-NuGet version conversion, Xcode/JDK/Android SDK requirements, CI sdkmanager packages, `packageid:Microsoft.Maui.Controls`. DO NOT USE FOR: installing workloads, build debugging, or app version edits.

Create iOS slim bindings for MAUI. USE FOR: slim iOS binding, Native Library Interop, Swift/Objective-C wrappers, XcodeGen project.yml, Podfile, CocoaPods static linking, BUILD_LIBRARY_FOR_DISTRIBUTION, XcodeProject MSBuild, `@objc`/`[Export]` selector crashes, async completion handlers. DO NOT USE FOR: Android bindings, general MAUI apps, or NuGet packaging.

Legacy DevFlow debug skill. USE FOR: `maui-ai-debugging`, `maui devflow`, screenshots, visual tree, Blazor CDP, simulator/emulator debugging. DO NOT USE FOR: setup, desktop automation, AppleScript, host `xdotool`.

Run DevFlow inspect-and-fix loops for MAUI apps. USE FOR: launch, device selection, agent recovery, broker/port/adb, tree/screenshot, Blazor CDP, iterative UI debugging. DO NOT USE FOR: first-time setup or non-MAUI automation. INVOKES: `maui devflow`, `dotnet`, `adb`, `simctl`.

Add DevFlow to a MAUI app. USE FOR: package refs, `MauiProgram` registration, Blazor WebView/GTK variants, verification after `maui devflow init`. DO NOT USE FOR: troubleshooting, debugging, UI inspection, or build failures. INVOKES: `maui devflow`, `dotnet`.

Review past MAUI DevFlow sessions. USE FOR: DevFlow friction reports, classifying `maui_tap`/`maui_hittest`/`maui_screenshot`/`maui_cdp_webviews` issues vs app bugs, markdown Environment/Findings reports, scrubbed dotnet/maui-labs issue drafts, workaround summaries. Does not run live `maui devflow`. DO NOT USE FOR: fixing bugs, onboarding, live debugging, or memory search.

{what this skill teaches agents}

Write and edit Comet Go single-file apps (.cs files using the Comet MVU framework for .NET MAUI). Use when writing, editing, or debugging Comet Go apps, or when the user mentions "maui go", "comet go", or is working with .cs files that import Comet.

Mandatory end-to-end verification for .NET MAUI and Comet app tasks. Enforces dependency ownership — broken tools and missing config are YOUR problem to fix, not blockers to report. USE FOR: any task touching UI, pages, navigation, services, or app behavior. Triggers: after code changes, before marking todos done, when reporting task results, when a tool fails. DO NOT USE FOR: documentation-only changes, squad config edits, or build system changes that don't affect the running app.

Guide .NET MAUI backend implementation for new platforms (GTK, AppKit, Avalonia, TUI, etc.) in the dotnet/maui-labs repository. USE FOR: creating a new MAUI backend, implementing a control handler, adding Essentials services, setting up build targets, scaffolding project structure, debugging handler rendering with DevFlow. DO NOT USE FOR: building or running existing MAUI apps (use maui-devflow-debug skill), DevFlow CLI/MCP tool development (see AGENTS.md). INVOKES: GitHub MCP tools for reference code, web_fetch for MAUI source and platform API docs.