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

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

3. Separation of Concerns
   Keep UI, business logic, and data access isolated in clear folder structures.

4. Cross-platform awareness
   Prefer abstractions over platform-specific code unless required.

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

   dotnet new maui -n [ProjectName]

2. Add MVVM base classes:

   • BaseViewModel
   • ObservableObject or INotifyPropertyChanged implementation
   • AsyncCommand helpers

3. Register services in MauiProgram.cs:

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

4. Configure global styles in Resources/Styles/Styles.xaml.

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