Skip to content

Using AI to Work on .NET MAUI

Jump to bottom
Shane Neuville edited this page Jan 29, 2026 · 11 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 Agent End-to-end workflow for fixing issues and reviewing PRs .github/agents/pr.md
Write Tests Agent Determines test type and invokes appropriate testing skill .github/agents/write-tests-agent.md
Sandbox Agent Manual testing and PR validation with Sandbox app .github/agents/sandbox-agent.md
Learn From PR Agent Extracts lessons from PRs and applies improvements .github/agents/learn-from-pr.md

PR Agent

Purpose: End-to-end workflow for investigating issues and reviewing/working on PRs.

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 PR Agent uses a 5-phase workflow:

  1. Pre-Flight - Context gathering from issues/PRs
  2. Tests - Create or verify reproduction tests exist
  3. Gate - Verify tests catch the issue (mandatory checkpoint)
  4. Fix - Explore fix alternatives using try-fix skill
  5. Report - Create PR or write review report

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

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

🔧 Fix & Review Skills

Skill Purpose Example Use
try-fix Attempts ONE alternative fix, tests it, reports results Used by PR agent in Fix phase
pr-finalize Verifies PR title/description match implementation finalize PR #12345
pr-build-status Retrieves Azure DevOps build info and Helix logs check build status for PR #12345

📋 Triage & Discovery Skills

Skill Purpose Example Use
find-reviewable-pr Finds PRs that need review, prioritized by importance find PRs to review
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?

📝 Automation Skills

Skill Purpose Example Use
ai-summary-comment Posts/updates progress comments on PRs Used by agents to report status

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

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
│   ├── pr.md                  # PR Agent (Phases 1-3)
│   ├── pr/post-gate.md        # PR Agent (Phases 4-5)
│   ├── sandbox-agent.md       # Sandbox testing agent
│   ├── write-tests-agent.md   # Test writing agent
│   └── learn-from-pr.md       # Learning agent
│
├── skills/                    # Reusable skills
│   ├── ai-summary-comment/    # PR comment posting
│   ├── find-reviewable-pr/    # PR discovery
│   ├── issue-triage/          # Issue triage
│   ├── learn-from-pr/         # PR analysis
│   ├── pr-build-status/       # Build status retrieval
│   ├── pr-finalize/           # PR finalization
│   ├── run-device-tests/      # Device 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 guidance
│   ├── uitests.instructions.md
│   ├── xaml-unittests.instructions.md
│   ├── sandbox.instructions.md
│   └── ...
│
└── 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