# Maui Devflow Onboard
> 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`.
- Skill: `shinyorg/maui-devflow-onboard` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add shinyorg/maui-devflow-onboard`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shinyorg/maui-devflow-onboard/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: shinyorg (https://skillmd.com/u/shinyorg)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shinyorg/maui-devflow-onboard
---
# DevFlow Onboard
Use this skill to add MAUI DevFlow to a project after `maui devflow init` has installed the DevFlow skills.
## When to Use
- The project has no `Microsoft.Maui.DevFlow.*` package references yet.
- The user asks how to onboard, initialize, install, integrate, or set up DevFlow.
- The agent needs to choose between standard, Blazor, GTK, or GTK + Blazor DevFlow packages.
- The repo uses Central Package Management and package edits need to be split correctly.
- `maui devflow init` has installed skills and the user asks for the next project edits.
## Route Elsewhere
- If package references and `AddMauiDevFlowAgent()` are already present but the CLI cannot connect, use `maui-devflow-debug`.
- If an agent is reachable and the user wants to inspect, tap, screenshot, or debug UI, use `maui-devflow-debug`.
## Optional Session Feedback Nudge
If onboarding required repeated DevFlow attempts, unclear package/version
workarounds, or a long setup session, ask whether the user wants to run
`maui-devflow-session-review` to summarize friction for MAUI DevFlow product
feedback. Do not run it automatically.
## Workflow
1. Optionally run `maui devflow skills check` and update bundled skills before editing if it reports `update-available-from-current-cli`.
2. Find MAUI app projects in the workspace. Prefer app projects with `UseMaui`, platform TFMs such as `net*-android`/`net*-ios`/`net*-maccatalyst`/`net*-windows`, or GTK MAUI package references.
3. Determine whether each target project is standard MAUI, MAUI + Blazor WebView, GTK, or GTK + Blazor.
4. Add the correct DevFlow package references. Respect Central Package Management if `Directory.Packages.props` is present.
5. Register DevFlow in `MauiProgram.cs` inside `#if DEBUG`.
6. Build and run the app.
7. Verify with:
```bash
maui devflow diagnose
maui devflow wait
maui devflow ui tree --depth 1
```
If verification fails after integration, switch to `maui-devflow-debug` for connectivity recovery.
## Stop Signals
- Stop before editing if multiple MAUI app projects exist and the user has not indicated which one to onboard.
- Stop and ask before enabling DevFlow outside Debug builds.
- Stop after package/registration edits and verify with a build before doing runtime debugging.
## Critical Anti-patterns
- Do not add versions to project `PackageReference` items when `Directory.Packages.props` is managing package versions.
- Do not add Blazor DevFlow packages unless the app uses Blazor WebView.
- Do not register DevFlow outside `#if DEBUG` unless the user explicitly asks.
- Do not use the old `builder.Services.AddMauiDevFlowAgent()` pattern; use `builder.AddMauiDevFlowAgent()`.
## Package Selection
| Project flavor | Required packages |
| --- | --- |
| Standard MAUI | `Microsoft.Maui.DevFlow.Agent` |
| MAUI + Blazor WebView | `Microsoft.Maui.DevFlow.Agent`, `Microsoft.Maui.DevFlow.Blazor` |
| GTK MAUI | `Microsoft.Maui.DevFlow.Agent.Gtk` |
| GTK MAUI + Blazor WebView | `Microsoft.Maui.DevFlow.Agent.Gtk`, `Microsoft.Maui.DevFlow.Blazor.Gtk` |
Blazor WebView indicators include a `Microsoft.AspNetCore.Components.WebView.Maui` package reference or `AddMauiBlazorWebView()` in `MauiProgram.cs`.
GTK indicators include package references such as `Maui.Gtk`, `Microsoft.Maui.Platforms.Linux.Gtk4`, `GirCore.Gtk-4.0`, or `Microsoft.Maui.Platforms.Linux.Gtk4.BlazorWebView` (older projects may still reference the pre-rename `Platform.Maui.Linux.Gtk4*` ids).
## Central Package Management
If the repo uses `Directory.Packages.props`, put versions there and leave project `PackageReference` entries versionless.
```xml
```
```xml
```
If the repo does not use Central Package Management, put the version on the `PackageReference`.
## MauiProgram.cs Registration
For standard MAUI:
```csharp
using Microsoft.Maui.DevFlow.Agent;
// inside CreateMauiApp(), before return builder.Build();
#if DEBUG
builder.AddMauiDevFlowAgent();
#endif
```
For MAUI + Blazor WebView:
```csharp
using Microsoft.Maui.DevFlow.Agent;
using Microsoft.Maui.DevFlow.Blazor;
// inside CreateMauiApp(), before return builder.Build();
#if DEBUG
builder.AddMauiDevFlowAgent();
builder.AddMauiBlazorDevFlowTools();
#endif
```
For GTK, use the `.Gtk` namespaces and packages. GTK apps also need to start the agent after app activation, for example `app.StartDevFlowAgent()` in the platform app activation flow.
For Mac Catalyst, ensure the Debug entitlements allow the in-app HTTP server:
```xml
com.apple.security.network.server
```
## Validation Checklist
- `MauiProgram.cs` registers DevFlow only in Debug builds.
- The app project references the package flavor that matches the target platform.
- Blazor DevFlow tools are added only when the app uses Blazor WebView.
- GTK apps start the DevFlow agent after app activation.
- Mac Catalyst Debug entitlements include `com.apple.security.network.server`.
- `dotnet build` succeeds.
- Important controls in the flows you plan to automate have stable `AutomationId`s.
- A running app appears in `maui devflow list`.
- `maui devflow agent status` returns the expected app name and platform.
- `maui devflow ui tree --depth 1` returns a visual tree.
## References
- See `references/package-selection.md` for package/flavor details.
- See `references/mauiprogram-registration.md` for registration patterns.