Skip to content
Skills Library
Programming · Testing

maui-devflow-debug

/maui-devflow-debug

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`.

Repository
health ↗
Licence
MIT
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
9
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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`.

Original author description

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`.

How it works

  1. When to Use
  2. Route Elsewhere
  3. Optional Session Feedback Nudge
  4. Core Loop
  5. Critical Anti-patterns
  6. Stop Signals
  7. Reference Map
Original SKILL.md headings · 107 lines, 734 words
SKILL.md preview
---
name: maui-devflow-debug
description: >-
  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`.
---

# DevFlow Debug

Use this skill for the active debugging loop after a MAUI app has DevFlow
packages and `builder.AddMauiDevFlowAgent()` registered.

## When to Use

- Build and run a MAUI app on Android, iOS, Mac Catalyst, macOS, Windows, or GTK.
- Choose or create a simulator/emulator for a project.
- Wait for a DevFlow agent, inspect the visual tree, tap/fill UI, or capture screenshots.
- Recover from DevFlow connection failures after the app is integrated, including broker, port, and Android adb forwarding issues.
- Debug Blazor Hybrid content through DevFlow WebView/CDP commands.
- Read app logs, network captures, preferences, device info, or recordings through DevFlow.
- Iterate on an app bug with a build -> deploy -> inspect -> fix loop.

## Route Elsewhere

- If DevFlow packages or `MauiProgram.cs` registration are missing, use `maui-devflow-onboard`.
- If the failure is a generic build or SDK issue with no DevFlow angle, use normal .NET/MAUI diagnostics.

## Optional Session Feedback Nudge

If you have retried the same MAUI DevFlow workflow several times, tried multiple
workarounds, or are ending a long DevFlow-assisted debugging 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.

## Core Loop

1. Confirm the app is already integrated:

   ```bash
   grep -rl "Microsoft.Maui.DevFlow" --include="*.csproj" .
   ```

   If no project has DevFlow package references, stop and switch to `maui-devflow-onboard`.

2. Pick the target framework and launch target. Do not assume `net10.0`; inspect the project first.

   ```bash
   grep -i "TargetFramework" *.csproj Directory.Build.props 2>/dev/null
   ```

3. Start or select the device/emulator. For Android and iOS, avoid reusing a simulator/emulator that is already running another app under investigation.

4. Launch the app and keep the launch process alive when required.

   - iOS, Android, and Mac Catalyst `dotnet build -t:Run` usually block for the app lifetime.
   - GTK `dotnet run` blocks for the app lifetime.
   - macOS AppKit builds can exit after compiling; launch the `.app` separately.

5. Wait for the DevFlow agent before inspecting UI:

   ```bash
   maui devflow wait
   maui devflow agent status
   maui devflow ui tree --depth 3 --fields "id,type,text,automationId"
   ```

   Treat `agent status` as the runtime truth for reachability and app identity.
   `diagnose` is broader environment state; it can report broker/project details
   without proving the current app is reachable.

   If `wait`, `list`, or `ui tree` cannot connect after the app is running, load `references/connectivity.md` and recover the broker/agent connection before continuing.

6. Prefer AutomationId-first validation for UI flows:

   ```bash
   maui devflow ui query --automationId save-button
   maui devflow ui tap <element-id-from-query>
   ```

   If important controls do not have stable `AutomationId`s, add them before
   relying on text, coordinates, screenshots, or brittle tree positions.

7. Inspect, interact, capture evidence, then edit the app and repeat from launch.

## Critical Anti-patterns

- Do not treat an empty `maui devflow list` as proof the project is not integrated. `list` is runtime state; project files are source of truth.
- Do not use arbitrary sleeps after launch. Use `maui devflow wait` to gate on the actual agent connection.
- Do not kill an async `dotnet build -t:Run` or `dotnet run` shell while you still need the app; that often kills the app.
- Do not reuse a busy simulator/emulator when multiple MAUI apps or agents may be running.
- Do not debug Blazor WebView DOM issues through the native visual tree alone; use the WebView/CDP commands.
- Do not drive key app flows by coordinates when AutomationIds are available or can be added.

## Stop Signals

- Stop and switch to `maui-devflow-onboard` when package references or `AddMauiDevFlowAgent()` are absent.
- Stop and ask which project, device, or agent to target when multiple candidates match.
- Stop rebuilding after two identical failures until you inspect the first meaningful build/runtime error.
- Stop using screenshots for exact property values; query the visual tree or properties instead.

## Reference Map

Load these only when needed:

- `references/setup.md` - detailed integration, package, entitlement, and update notes.
- `references/connectivity.md` - broker, agent, port, Android forwarding, and "no agents connected" recovery.
- `references/android.md` - Android SDK, emulator, adb, build, deploy, and port forwarding details.
- `references/ios-and-mac.md` - iOS simulator, Mac Catalyst, permissions, entitlements, and Apple tooling.
- `references/macos.md` - macOS AppKit project shape, launch model, and troubleshooting.
- `references/linux.md` - GTK/Linux launch, packages, and WebKitGTK notes.
- `references/batch.md` - batching multiple DevFlow UI/WebView operations.
- `references/troubleshooting.md` - build, connection, CDP, and platform-specific failure recovery.
Files in this package (9)
  • SKILL.md 5 KB
  • references/android.md 8 KB
  • references/batch.md 2 KB
  • references/connectivity.md 5 KB
  • references/ios-and-mac.md 14 KB
  • references/linux.md 6 KB
  • references/macos.md 7 KB
  • references/setup.md 13 KB
  • references/troubleshooting.md 7 KB

Versions

RepositoryScoreLicence
This page · shinyorg/health100MIT
yurkinh/plugin.maui.calendar100MIT

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 858b1b46a6ff (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100maui-devflow-onboard
    Add MAUI DevFlow to a .NET MAUI project with agent package references, MauiProgram.cs registration, Blazor WebView support, GTK variants, Central Package Management guidance, and verification commands. USE FOR: first-time DevFlow setup, reviewing what files to edit, choosing…
  • 100maui-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`.
  • 100maui-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`.
  • 90maui-devflow-session-review
    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…
  • 100devflow
    Use when working in a DevFlow project with .devflow/ directory and gate-based step-by-step workflows
  • 100skiaui-devflow
    Adds SkiaUi support to .NET MAUI DevFlow in an app that uses SkiaUi (SkiaUi.Maui, SkUi* controls), so DevFlow and AI agents can find, tap and hit-test drawn controls, which have no platform views and are invisible or untappable through DevFlow's own tree. Copies the dev.skiaui…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.