name: flutter-dev
description: Expert guidance for Flutter and Dart development. Use when building Flutter apps, implementing state management, setting up routing, writing tests, or working with Flutter UI components. Provides access to detailed rules for Bloc, Riverpod, Provider, Mocktail, and more.

Flutter Development Skill

Overview

This Skill provides modular Flutter development guidance with access to detailed documentation for specific libraries and patterns.

Quick Start: When user mentions a specific library (e.g., "use Bloc", "Riverpod", "GoRouter"), read the corresponding ./rules/*.md file before responding.

Module 1: State Management

Core Principles

• Prefer built-in solutions for simple state (ValueNotifier, ChangeNotifier, StreamBuilder)
• Choose state management based on complexity and team familiarity
• Read detailed rules when using specific libraries

Extended Rules Index

Usage: Read the rule file when user mentions trigger keywords.

Quick Reference

For simple state: Start with ChangeNotifier or ValueNotifier
For complex apps: Use Bloc or Riverpod
When unsure: Ask user about their preferences and app complexity

Module 2: Testing

Core Principles

• Write tests that can actually fail if real code is broken
• Use Mocktail for mocks (preferred over Mockito)
• Always use group() for test organization

Extended Rules Index

Testing Checklist

Test Quality Checklist:
- [ ] Test can fail if real code is broken
- [ ] Tests are grouped with group()
- [ ] Test names use "should" format
- [ ] Mocks are used appropriately

Module 3: Navigation & Routing

Core Principles

• Use GoRouter for all navigation (declarative approach)
• Prefer named routes over hardcoded paths
• Centralize route definitions

Extended Rules Index

Quick Reference

// Navigation actions
context.goNamed('profile')      // Switch screen
context.pushNamed('details')     // Stack screen
context.pop()                    // Go back

Module 4: Code Quality & Standards

Core Principles

• Follow Effective Dart guidelines
• Use dart analyze and dart format regularly
• Write self-documenting code with clear naming

Extended Rules Index

Naming Standards

Code Quality Checklist

- [ ] Functions < 20 lines
- [ ] Single responsibility per function
- [ ] Descriptive names, no abbreviations
- [ ] Proper error handling with developer.log()
- [ ] Run: dart analyze && dart format .

Module 5: Architecture & Data

Core Principles

• Separate concerns: Presentation, Business Logic, Data layers
• Use repositories to abstract data sources
• Keep business logic out of UI widgets

Extended Rules Index

Architecture Layers

┌─────────────────────────────────┐
│   Presentation Layer (UI)        │
│   - Widgets                      │
│   - Blocs/Cubits/Providers       │
└─────────────────────────────────┘
              ↓
┌─────────────────────────────────┐
│   Business Logic Layer          │
│   - Use cases / Services         │
│   - Business rules               │
└─────────────────────────────────┘
              ↓
┌─────────────────────────────────┐
│   Data Layer                     │
│   - Repositories                 │
│   - Data sources (API, DB)       │
└─────────────────────────────────┘

Common Workflows

Workflow: New Flutter Feature

Feature Development Progress:
- [ ] 1. Define data models (with json_serializable if needed)
- [ ] 2. Create repository/service layer
- [ ] 3. Implement business logic (use appropriate state management)
- [ ] 4. Build UI widgets (break into small components)
- [ ] 5. Write tests (unit → widget → integration)
- [ ] 6. Run: dart analyze && dart format

When user starts a new feature: Reference this workflow and ask which step they're on.

Workflow: Choosing State Management

State Management Decision Tree:
1. Is state simple and local? → ValueNotifier / ChangeNotifier
2. Is state complex/shared? → Bloc / Riverpod / Provider
3. Does user/event tracking matter? → Bloc
4. Is type safety a priority? → Riverpod
5. What does the team prefer? → Ask user

Workflow: Setting Up Navigation

GoRouter Setup Checklist:
- [ ] 1. Add go_router dependency
- [ ] 2. Create app_router.dart with route definitions
- [ ] 3. Use MaterialApp.router in main.dart
- [ ] 4. Define routes with GoRoute (path, name, builder)
- [ ] 5. Implement guards/redirect if needed
- [ ] 6. Test navigation flows

Anti-patterns to Avoid

Troubleshooting Guide

Common Errors

Debugging Commands

# Analyze code
dart analyze

# Format code
dart format .

# Run tests
flutter test

# Check dependencies
flutter pub deps

Quick Command Reference

# Project creation
flutter create my_app

# Dependency management
flutter pub add <package>
flutter pub remove <package>
flutter pub upgrade

# Code quality
dart analyze
dart format .
dart fix --apply

# Testing
flutter test
flutter test --coverage

References

• evanca/flutter-ai-rules - Source of these rules
• Flutter Documentation
• Dart Language Guide