Skip to content

Using AI to Work on .NET MAUI

Jump to bottom
kubaflo edited this page Jul 1, 2026 · 13 revisions

This guide helps you use GitHub Copilot effectively when working on the .NET MAUI repository.

Table of Contents

Prerequisites

Before using the AI agents and skills, ensure you have:

  • GitHub Copilot access - Active subscription with CLI or VS Code extension
  • VS Code - With GitHub Copilot extension installed
  • .NET MAUI development environment - See Windows Install or macOS Install
  • Cloned .NET MAUI repository - git clone https://github.com/dotnet/maui.git
  • For Sandbox testing: Android emulator and/or iOS simulator configured

Export Your Chat Sessions

If you use any of our agents or just Copilot in general to work on an issue:

  1. End with a message summarizing your experience
  2. Export the chat session:
    • Copilot CLI: Use /share file to save as markdown or /share gist to create a GitHub gist
    • VS Code: Export as JSON
  3. Attach the exported session to your PR

Custom Agents

The .NET MAUI repository includes specialized AI agents designed to help with specific development tasks. These agents are available through GitHub Copilot and provide expert assistance for common workflows.

How to Use Custom Agents

In VS Code: Custom Agents in VS Code

In GitHub Copilot CLI: GitHub Copilot CLI

Pro Tip: Use Plan Mode for Complex Tasks

For best results with complex tasks like PR reviews, use plan mode first:

  1. Press Shift+Tab to enter plan mode (or use /plan)
  2. Ask Copilot to create a detailed plan for your task
  3. Review and refine the plan
  4. Press Shift+Tab to exit plan mode
  5. Tell Copilot to proceed with the plan

This gives you control over the approach before any actions are taken.

Available Agents

Agent Description Location
PR Review Workflow End-to-end workflow for fixing issues and reviewing PRs .github/skills/pr-review/SKILL.md + Review-PR.ps1
Write Tests Agent Determines test type and invokes appropriate testing skill .github/agents/write-tests-agent.agent.md
Sandbox Agent Manual testing and PR validation with Sandbox app .github/agents/sandbox-agent.agent.md
Learn From PR Agent Extracts lessons from PRs and applies improvements .github/agents/learn-from-pr.agent.md
Agentic Workflows Agent Dispatcher for creating, updating, and debugging gh-aw workflows .github/agents/agentic-workflows.agent.md
MAUI Expert Reviewer Deep 30-dimension code review for the automated pipeline .github/agents/maui-expert-reviewer.md

PR Review Workflow

Purpose: End-to-end workflow for investigating issues and reviewing/working on PRs. Orchestrated by Review-PR.ps1 and the pr-review skill.

When to use: When you need to fix an issue (with or without an existing PR), review a PR with independent analysis, or continue work on an in-progress fix.

The workflow runs these steps:

  1. Gate - Verify tests catch the issue (script-only, no AI)
  2. Pre-Flight - Context gathering from issues/PRs
  3. Try-Fix - 4 AI models explore independent fix alternatives
  4. Report - Expert hardening and final recommendation

Example prompts:

  • fix issue #12345
  • review PR #12345
  • work on issue #12345
  • continue working on #12345

Write Tests Agent

Purpose: Determines what type of tests are needed and invokes the appropriate skill.

When to use: When creating new tests for issues or PRs.

Supported test types:

  • UI Tests - via write-ui-tests skill (visual bugs, user interactions)
  • XAML Tests - via write-xaml-tests skill (XAML parsing, compilation, source generation)

Example prompts:

  • write tests for issue #12345
  • create tests for this PR
  • add test coverage for CollectionView selection

Sandbox Agent

Purpose: Test and validate PR functionality using the Sandbox app with automated deployment and testing.

When to use: When you want to manually verify a fix works on device/simulator, reproduce an issue, or validate PR functionality.

Example prompts:

  • test PR #12345 on Android
  • reproduce issue #12345 in Sandbox
  • test this PR on iOS

Learn From PR Agent

Purpose: Extracts lessons from completed PRs and applies improvements to the repository.

When to use: After complex PRs, when agents struggled to find solutions, or to improve instruction files and skills based on lessons learned.

Example prompts:

  • learn from PR #12345 and apply improvements
  • improve repo based on what we learned
  • update skills based on PR

Agentic Workflows Agent

Purpose: Dispatcher for GitHub Agentic Workflows — helps create, update, debug, upgrade, and report on gh-aw workflows.

When to use: When you need to work with the automated workflow infrastructure (.github/workflows/*.md files and their generated .lock.yml files).

Example prompts:

  • create a new agentic workflow
  • debug the agentic-labeler workflow
  • upgrade all workflows to latest gh-aw version

Note: This agent has disable-model-invocation: true — it routes to specific prompt templates rather than generating solutions itself.

MAUI Expert Reviewer

Purpose: Deep PR reviewer that evaluates code across 30 dimensions covering layout, handlers, platform specifics, performance, API design, CollectionView, navigation, XAML, accessibility, and regression patterns.

When to use: Primarily used internally by the code-review skill and the automated PR review pipeline. Can also be invoked directly for thorough per-dimension analysis.

Capabilities:

  • Runs per-dimension sub-agent evaluation in parallel
  • Writes inline findings as structured JSON
  • Covers MAUI-specific patterns that general code review misses

Reusable Skills

Skills are modular capabilities that provide specialized functionality for common workflows. Think of them as building blocks that can be used directly or composed by agents to accomplish larger tasks.

Why Skills?

Skills encapsulate expert knowledge about specific tasks - like writing UI tests, verifying test quality, or exploring fix alternatives. They:

  • Reduce errors by encoding best practices and conventions
  • Save time by automating repetitive workflows
  • Ensure consistency across different contributors
  • Enable agents to perform complex multi-step operations

Skills vs Agents

Aspect Skills Agents
Scope Single-purpose operations Multi-phase workflows
State Stateless Track state across phases
Invoke Direct request or by agents Delegate to agent
Output Specific result (tests, analysis, status) Complete solution with documentation
Example "Verify these tests fail" "Fix issue #12345 end-to-end"

Skill Categories

🧪 Testing Skills

Skill Purpose Example Use
write-ui-tests Creates UI tests for GitHub issues write UI test for issue #12345
write-xaml-tests Creates XAML unit tests for parsing/compilation write XAML test for binding issue
verify-tests-fail-without-fix Verifies tests actually catch the bug Used by agents after test creation
run-device-tests Runs device tests locally on iOS/Android/Windows run Button tests on iOS
run-helix-tests Submits and monitors unit tests on Helix infrastructure run XAML unit tests on Helix
run-integration-tests Builds, packs, and runs integration tests locally run integration tests
evaluate-pr-tests Evaluates test quality, coverage, and appropriateness evaluate tests on PR #12345

🔍 PR Review Skills

Skill Purpose Example Use
pr-review End-to-end PR reviewer (Pre-Flight → Try-Fix → Report) review PR #12345
code-review Standalone deep code review with MAUI-specific rules code review PR #12345
try-fix Attempts ONE alternative fix, tests it, reports results Used by pr-review in Try-Fix phase
pr-finalize Verifies PR title/description match implementation finalize PR #12345
find-reviewable-pr Finds PRs that need review, prioritized by importance find PRs to review

📋 Triage & Discovery Skills

Skill Purpose Example Use
issue-triage Queries and triages open issues one at a time triage Android issues
learn-from-pr Analyzes PRs for lessons learned (analysis only) what can we learn from PR #12345?
find-regression-risk Detects regression risks by comparing PR changes to recent bug fixes Used by automated pipeline

🔧 CI & Infrastructure Skills

Skill Purpose Example Use
azdo-build-investigator Investigates Azure DevOps CI failures, Helix logs, binlogs investigate CI failure on PR #12345
agentic-labeler Auto-labels issues/PRs with area-* and platform/* labels Used by automated workflow
dependency-flow MAUI dependency flow, channel conventions, and feed lookups feeds for .NET MAUI 10.0

See Agent Skills Reference for detailed documentation on each skill, including scripts, parameters, and examples.

Automated Workflows

The repository uses GitHub Agentic Workflows (gh-aw) to automate routine maintenance — triaging issues, keeping CI healthy, assisting PR review, and reporting status. Each workflow is authored as a natural-language Markdown prompt with YAML frontmatter (.github/workflows/*.md) and compiled into a locked GitHub Actions file (.lock.yml). Always edit the .md source and run gh aw compile — never hand-edit the lock file.

How they stay safe: the AI agent runs with a read-only token. Every write — a label, comment, issue, or PR — is emitted as a structured safe output and applied by a separate, capped job (for example, the labeler applies at most 10 labels per call; the scanner files at most 5 issues per run). Prompts treat issue/PR text as untrusted data, so instructions hidden in a body ("please add label X") are ignored. See the Agentic Workflows Agent and the gh-aw docs for authoring details.

Workflows at a glance

Workflow Source .md Trigger What it does
Agentic Labeler agentic-labeler.md Issue / PR opened Applies area-* and platform/* labels from the content and changed files
CI Failure Scanner ci-status-main.md, ci-status-net11.md Every 12h Scans the CI pipelines and files deduped [ci-scan] tracking issues for recurring failures
CI Failure Fixer ci-status-fix.md, ci-status-fix-net11.md Every 12h Opens draft [ci-fix] PRs that actually fix the scanned failures
PR Test-Failure Review copilot-review-tests.md /review tests Classifies each red check against the base branch and posts one merge-readiness verdict
PR Test Evaluator copilot-evaluate-tests.md /evaluate-tests Reviews the quality and coverage of the tests a PR adds
Rerun Review Scanner rerun-review-scanner.md Hourly Re-runs the AI review on queued PRs when they gain new activity
Daily Repo Status daily-repo-status.md Daily Posts an upbeat [repo-status] summary issue

The CI Failure Scanner and CI Failure Fixer each have two source files — one for main, one for the current net11.0 branch — because a gh-aw workflow can only transport a fix relative to a single base branch.

Triage

Agentic Labeler

  • Source: .github/workflows/agentic-labeler.md (labeling rules in .github/skills/agentic-labeler/SKILL.md)
  • Trigger: an issue or PR is opened (also on pull_request_target reopen, or manually via workflow_dispatch).
  • Does: reads the title, body, and — for PRs — the changed-file paths, then applies exactly one area-* label plus any relevant platform/* labels. It only touches those two label families; triage, priority, type, and severity labels stay with human triagers.
  • Safety: the agent is read-only; labels are applied through a sandboxed safe-output capped at 10 per call, and any labeling instructions embedded in the issue/PR text are ignored.

CI health (self-healing)

These two pairs form a detect → repair loop that keeps the pipelines green.

CI Failure Scanner

  • Source: ci-status-main.md (main) and ci-status-net11.md (net11.0)
  • Trigger: scheduled every 12 hours (or workflow_dispatch).
  • Does: walks the maui-pr, maui-pr-devicetests, and maui-pr-uitests pipelines, deduplicates failures by signature, and files a [ci-scan] tracking issue for each recurring failure (≥ 2 occurrences), build break, or infrastructure problem. Capped at 5 new issues per run.
  • Output: [ci-scan]-labelled tracking issues — the hand-off surface for the fixer and for human triage.

CI Failure Fixer

  • Source: ci-status-fix.md (main) and ci-status-fix-net11.md (net11.0)
  • Trigger: scheduled every 12 hours (or workflow_dispatch, optionally scoped to a single issue).
  • Does: picks up open [ci-scan] issues, reproduces the failure, and opens a draft [ci-fix] PR that fixes it. It de-flakes tests with deterministic synchronization (never by muting them or adding retries/timeout bumps), edits only allow-listed src/** paths (never .github/), retries up to 5 times across runs, and then defers to a human. Runs on Claude Opus.
  • Output: draft [ci-fix] PRs against the matching branch.

PR review assistance

PR Test-Failure Review

  • Source: copilot-review-tests.md (skill: .github/skills/review-test-failures/SKILL.md)
  • Trigger: comment /review tests on a PR (collaborators with write access), or workflow_dispatch.
  • Does: for every failing, pending, or inconclusive check it computes a baseline diff against the most recent base-branch build and classifies each failure as likely PR-caused, pre-existing, or a known issue. A deterministic gate caps the verdict, so a green "ready to merge" is impossible while anything is unexplained.
  • Output: a single merge-readiness verdict comment (Ready to merge / Not ready / Needs human investigation / Insufficient data).

PR Test Evaluator

  • Source: copilot-evaluate-tests.md (skill: .github/skills/evaluate-pr-tests/SKILL.md)
  • Trigger: comment /evaluate-tests on a PR that adds or modifies tests (collaborators with write access), or workflow_dispatch.
  • Does: judges whether the new tests actually cover the change, looks for missing edge cases, and recommends the lightest appropriate test type (prefer unit over device over UI).
  • Output: one evaluation comment (adequate / needs improvement / insufficient).

Rerun Review Scanner

  • Source: rerun-review-scanner.md
  • Trigger: scheduled hourly (or workflow_dispatch, with a dry-run option).
  • Does: watches PRs labelled s/agent-ready-for-rerun, decides whether the new commits or comments since the last review justify another pass, and — if so — re-dispatches the same review pipeline a maintainer's /review runs. Runs are serialized and head-SHA-validated, so a PR is never double-reviewed. This is what makes the review loop self-healing.
  • Output: a re-triggered AI review (it posts no comments of its own).

Reporting

Daily Repo Status

  • Source: daily-repo-status.md
  • Trigger: scheduled daily (or workflow_dispatch).
  • Does: gathers recent issue, PR, release, and code activity and posts an upbeat [repo-status] status issue with highlights and suggested next steps; it closes the previous day's report automatically.
  • Output: a [repo-status] issue labelled daily-status.

Interacting with the workflows

Most run on their own, but three respond to you directly:

You do this And this happens
Comment /review tests on a PR PR Test-Failure Review posts a merge-readiness verdict
Comment /evaluate-tests on a PR PR Test Evaluator reviews the PR's tests
Add the s/agent-ready-for-rerun label to a PR The Rerun Review Scanner re-runs the AI review on its next hourly pass

The two slash commands require write access to the repository.

⚠️ Never edit .lock.yml files directly. Edit the .md source, then run gh aw compile and commit both files together.

Instruction Files

Instruction files provide context-specific coding guidance that Copilot automatically uses when working with matching file patterns. They're located in .github/instructions/ and cover:

Category Files Topics
Handlers handler-patterns, collectionview-* (4 files) Mapper rules, lifecycle, null-safety, platform-specific CollectionView guidance
Platform android, safe-area-ios, threading-async Android coding rules, iOS safe area behavior, threading/async patterns
Testing uitests, xaml-unittests, helix-device-tests, integration-tests, sandbox Test authoring guidelines per test type
Performance performance-hotpaths, layout-system Hot-path optimization, layout measure/arrange contract
API public-api, templates PublicAPI.Unshipped.txt management, template editing rules

These files are automatically loaded based on glob patterns matching the files you're editing. See .github/copilot-instructions.md for the full pattern-to-file mapping.

Using Copilot with Git

GitHub Copilot can handle git operations for you - committing changes, squashing commits, rebasing branches, resolving conflicts, and creating PR descriptions.

See the Using Copilot with Git Guide for detailed examples and prompts.

Repository Structure

All agent and skill definitions live in the .github/ directory:

.github/
├── agents/                              # Custom agent definitions
│   ├── agentic-workflows.agent.md       # Agentic Workflows dispatcher
│   ├── write-tests-agent.agent.md       # Test writing agent
│   ├── sandbox-agent.agent.md           # Sandbox testing agent
│   ├── learn-from-pr.agent.md           # Learning agent
│   └── maui-expert-reviewer.md          # 30-dimension PR reviewer
│
├── skills/                              # Reusable skills
│   ├── agentic-labeler/                 # Auto-labeling
│   ├── azdo-build-investigator/         # CI failure investigation
│   ├── code-review/                     # Deep code review
│   ├── dependency-flow/                 # Dependency flow & feeds
│   ├── evaluate-pr-tests/               # Test quality evaluation
│   ├── find-regression-risk/            # Regression risk detection
│   ├── find-reviewable-pr/              # PR discovery
│   ├── issue-triage/                    # Issue triage
│   ├── learn-from-pr/                   # PR analysis
│   ├── pr-finalize/                     # PR finalization
│   ├── pr-review/                       # End-to-end PR review orchestrator
│   ├── run-device-tests/                # Device test execution
│   ├── run-helix-tests/                 # Helix test submission
│   ├── run-integration-tests/           # Integration test execution
│   ├── try-fix/                         # Fix exploration
│   ├── verify-tests-fail-without-fix/   # Test verification
│   ├── write-ui-tests/                  # UI test creation
│   └── write-xaml-tests/                # XAML test creation
│
├── instructions/                        # Context-specific coding guidance
│   ├── uitests.instructions.md
│   ├── xaml-unittests.instructions.md
│   ├── sandbox.instructions.md
│   ├── handler-patterns.instructions.md
│   └── ... (17 files total)
│
├── pr-review/                           # PR review phase instructions
│   ├── pr-preflight.md                  # Pre-flight context gathering
│   ├── pr-gate.md                       # Gate verification rules
│   └── pr-report.md                     # Report generation
│
├── scripts/                             # Orchestration scripts
│   ├── Review-PR.ps1                    # PR review pipeline orchestrator
│   ├── BuildAndRunHostApp.ps1           # UI test host app builder
│   ├── BuildAndRunSandbox.ps1           # Sandbox app builder
│   ├── Find-RegressionRisks.ps1         # Regression risk detector
│   ├── EstablishBrokenBaseline.ps1      # Baseline management for try-fix
│   ├── post-ai-summary-comment.ps1      # Posts AI review summary to PR
│   └── shared/                          # Shared utilities
│
├── workflows/                           # GitHub Agentic Workflows (gh-aw)
│   ├── agentic-labeler.md               # Auto-labeling (area-*/platform-*)
│   ├── ci-status-main.md                # CI Failure Scanner (main)
│   ├── ci-status-net11.md               # CI Failure Scanner (net11.0)
│   ├── ci-status-fix.md                 # CI Failure Fixer (main)
│   ├── ci-status-fix-net11.md           # CI Failure Fixer (net11.0)
│   ├── copilot-review-tests.md          # PR Test-Failure Review (/review tests)
│   ├── copilot-evaluate-tests.md        # PR Test Evaluator (/evaluate-tests)
│   ├── rerun-review-scanner.md          # Rerun Review Scanner (hourly)
│   └── daily-repo-status.md             # Daily Repo Status (daily)
│
└── copilot-instructions.md              # Main repository instructions

Troubleshooting

Agent seems stuck or taking too long

Long-running operations are normal:

  • PR Agent full workflow: 25-60 minutes total
  • Test verification: 5-15 minutes per platform
  • Sandbox builds: 5-10 minutes first build

If truly stuck, check if there's a prompt waiting for input. You can also try: "what's the current status?"

Tests won't fail (can't reproduce the bug)

  • Verify you're testing on the correct platform
  • Check if the reproduction steps from the issue are complete
  • Try asking: "show me the test scenario and what it's checking"
  • If tests pass when they shouldn't, the test scenario may not match the bug

Build failures

Before running tests or agents:

  1. Build the MSBuild tasks first: dotnet build Microsoft.Maui.BuildTasks.slnf
  2. Ensure you have the correct .NET SDK (check global.json)

Gate phase keeps failing

Gate fails when tests don't properly catch the bug. Common causes:

  • Tests pass without the fix (tests don't reproduce the bug)
  • Tests fail with the fix (fix doesn't work)
  • Wrong platform being tested

Ask: "why did Gate fail?" for specific guidance.

Session times out or gets confused

For long workflows, use plan mode to maintain control:

  1. Shift+Tab to enter plan mode
  2. Create a plan for your task
  3. Execute in smaller steps

You can also use /share file to save progress before continuing.

General Info

Getting Started

Using AI to Work on .NET MAUI

When things go wrong

Migration

Publishing

Blogs

Clone this wiki locally