.NET MAUI — Project Setup Skill

Purpose

This skill provides agents with a standardized, production-ready approach to creating and structuring .NET MAUI applications. It defines folder conventions, MVVM architecture defaults, dependency injection patterns, and cross-platform considerations that should be applied whenever a new MAUI project is initialized.

The goal is to ensure that all generated MAUI projects follow consistent, maintainable, and scalable patterns.

Core Principles

1. MVVM-first architecture

Use ViewModels, observable properties, and commands as the primary interaction pattern.

1. Dependency Injection

Register services in MauiProgram.cs using the built-in DI container.

1. Separation of Concerns

Keep UI, business logic, and data access isolated in clear folder structures.

1. Cross-platform awareness

Prefer abstractions over platform-specific code unless required.

1. Scalable folder structure

Organize code into predictable, discoverable modules.

Recommended Folder Structure

[root]
├─ Models
│  └─ [Add model classes here]
├─ Platforms
│  └─ [Add platform-specific setup and code here]
├─ Resources
│  ├─ AppIcon
│  │  └─ [Add application icon files here]
│  ├─ Fonts
│  │  └─ [Add font files here]
│  ├─ Images
│  │  └─ [Add image files here]
│  ├─ raw
│  │  └─ [Add raw files here]
│  ├─ Splash
│  │  └─ [Add splash screen files here]
│  └─ Styles
│     └─ [Add style files here]
├─ Services
│  ├─ Interfaces
│  │  └─ [Add service interfaces here]
│  └─ [Add service classes here]
├─ ViewModels
│  ├─ MainViewModel.cs
│  └─ [Add other ViewModels here]
├─ Views
│  ├─ Controls
│  │  └─ [Add custom controls here]
│  ├─ MainPage.xaml
│  │  └─ MainPage.xaml.cs
│  └─ Templates
│    └─ [Add custom templates here]
├─ App.xaml
│  └─ App.xaml.cs
└─ MauiProgram.cs

Project Initialization Steps

1. Create a new MAUI project:

``code dotnet new maui -n [ProjectName] ``

1. Add MVVM base classes:

- BaseViewModel - ObservableObject or INotifyPropertyChanged implementation - AsyncCommand helpers

1. Register services in MauiProgram.cs:

``code builder.Services.AddSingleton<INavigationService, NavigationService>(); builder.Services.AddTransient<MainViewModel>(); builder.Services.AddTransient<MainPage>(); ``

1. Configure global styles in Resources/Styles/Styles.xaml.
2. Add platform assets:

- App icons - Splash screens - Permissions manifests

Agent Usage Guidelines

• Always scaffold new MAUI apps using the folder structure above (Change it after project creation).
• When generating code, place files in the correct folders.
• When asked to “create a new page,” generate both:

- Views/MyPage.xaml - ViewModels/MyPageViewModel.cs

• When asked to “add a service,” create:

- Services/Interfaces/IServiceName.cs - Services/ServiceName.cs

• Register it in MauiProgram.cs.

Out of Scope

• Deep UI best practices (covered in maui-ui-best-practices)
• Authentication flows (covered in maui-authentication)
• Deployment (covered in maui-deployment)