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

• Prerequisites - What you need before starting
• Custom Agents - Specialized agents for specific MAUI tasks
• Reusable Skills - Modular capabilities for common workflows
• Automated Workflows - GitHub Agentic Workflows that run automatically
• Instruction Files - Context-specific coding guidance
• Using Copilot with Git - Let Copilot handle your git operations
• Troubleshooting - Common issues and solutions

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

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

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.

In VS Code: Custom Agents in VS Code

In GitHub Copilot CLI: GitHub Copilot CLI

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.

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

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

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

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

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.

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

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.

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

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

The repository uses GitHub Agentic Workflows (gh-aw) to automate routine tasks. Each workflow has a source .md file and a generated .lock.yml file — always edit the .md file and run gh aw compile to regenerate the lock file.

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

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:

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.

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.

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 workflow
│   ├── copilot-evaluate-tests.md        # Test evaluation workflow
│   └── daily-repo-status.md             # Daily status report
│
└── copilot-instructions.md              # Main repository instructions

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?"

• 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

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

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.