# flutter-dev

> A Claude Code skill from MiniMax-AI's skills repo for Flutter 3 cross-platform development — widget patterns, Riverpod and Bloc state management, GoRouter navigation, performance discipline (const constructors, RepaintBoundary, isolates), responsive layouts, and the testing pyramid.

**Use case**: Build a Flutter app where const optimization, selective Riverpod rebuilds, and 60 fps animation discipline are the default — not the post-launch retrofit

**Canonical URL**: https://agentcookbooks.com/skills/flutter-dev/

**Topics**: claude-code, skills, mobile

**Trigger phrases**: "scaffold a Flutter app", "Riverpod state for this widget", "fix Flutter rebuild jank"

**Source**: [MiniMax-AI](https://github.com/MiniMax-AI/skills/tree/main/skills/flutter-dev)

**License**: MIT

---

## What it does

`flutter-dev` is the Flutter skill in [MiniMax-AI's skills repo](https://github.com/MiniMax-AI/skills) — a Flutter 3 + Dart guide that opens with two quick-reference tables. The widget table maps purpose to component (`StateProvider` + `ConsumerWidget` for simple state, `NotifierProvider` / `Bloc` for complex, `FutureProvider` / `AsyncNotifierProvider` for async, `StreamProvider` for streams, `GoRouter` for navigation, `LayoutBuilder` for responsive, `ListView.builder` for lists, `CustomScrollView` + Slivers for complex scrolling, `HookWidget` for hooks, `Form` + `TextFormField` for forms). The performance table maps the symptom to the fix (`const` constructors to prevent rebuilds, `ref.watch(provider.select(...))` for selective updates, `RepaintBoundary` to isolate repaints, `ListView.builder` for lazy lists, `compute()` for heavy work in an isolate, `cached_network_image` for image caching).

Core principles run through widget optimization (const constructors wherever possible, extract static widgets, use `Key` for list items, prefer `ConsumerWidget` over `StatefulWidget`), state management (Riverpod for DI + simple state, Bloc/Cubit for event-driven workflows, never mutate state, use `select()`), layout (8 pt spacing, mobile/tablet/desktop breakpoints, Material 3 / Cupertino), and performance (profile with DevTools first, target <16 ms frame time for 60 fps, `RepaintBoundary` for complex animations, offload heavy work).

The closing section is a five-part checklist (widget best practices, state management, navigation, performance, testing) and a reference table that links to deeper guides — `references/widget-patterns.md`, `references/riverpod-state.md`, `references/bloc-state.md`, `references/gorouter-navigation.md`, `references/project-structure.md`, `references/performance.md`, `references/testing.md`.

## When to use it

- Starting a new Flutter 3 + Dart app where you want the const-constructor and selective-rebuild discipline baked in from the first widget
- Picking between Riverpod and Bloc for a specific feature's state shape (Riverpod for DI + simple, Bloc for event-driven)
- Setting up `GoRouter` with typed routes, auth-guard redirects, deep-linking, state preservation across routes
- Profiling a Flutter app that's dropping frames — DevTools-led optimization with the symptom→fix table as the spine
- Writing widget tests, integration tests, and `blocTest()` cases for an existing feature

When *not* to reach for it:

- Android-only or iOS-only — `android-native-dev` or `ios-application-dev` give you platform-specific HIG/Material conformance you don't get cross-platform
- Flutter Web with custom rendering targets where the skill's mobile-first patterns don't carry
- Game UI on Flutter (Flame engine) — the skill is widget-tree-shaped, not game-loop-shaped
- Pure Dart server-side work (Shelf, Aqueduct) — Flutter UI primitives don't apply

## Install

From [MiniMax-AI/skills](https://github.com/MiniMax-AI/skills) at `skills/flutter-dev/`. Drop into `~/.claude/skills/flutter-dev/`. Plugin marketplace install: `claude plugin marketplace add https://github.com/MiniMax-AI/skills` then `claude plugin install minimax-skills`.

The skill itself is pattern + checklist text — the toolchain (Flutter SDK 3.x, Dart, Android Studio or Xcode for emulator/simulator, DevTools) is installed locally outside the skill.

## What a session looks like

1. **Widget pick.** Skill consults the widget pattern table and picks `ConsumerWidget` (Riverpod simple state) or `BlocBuilder` (event-driven), `ListView.builder` for lists, `LayoutBuilder` for responsive layout, `GoRouter` + `context.go` for navigation.
2. **State shape decision.** Riverpod or Bloc — the skill picks based on whether the feature is data-shaped (Riverpod) or event-shaped (Bloc), and codes immutable state objects with `select()` for granular rebuilds.
3. **Layout pass.** 8 pt grid spacing, breakpoints at 650 (tablet) and 1100 (desktop), flexible widths.
4. **Const + Key pass.** Every static widget gets a `const` constructor; every list item gets a `ValueKey` or `ObjectKey`. The "no widget building inside `build()`" rule is enforced — extract reusable widgets to separate files.
5. **Navigation setup.** `GoRouter` with typed routes, auth-guard redirect, deep-link handling, state preservation across routes.
6. **Performance pass (if needed).** Run `flutter run --profile`, open DevTools, look at the timeline. Target <16 ms frame time. `RepaintBoundary` around complex animations. `compute()` for heavy work. Cache network images with `cached_network_image`.
7. **Test pass.** Widget tests for UI, unit tests for business logic, integration tests for flows, `blocTest()` for event-driven state.
8. **Checklist runtime.** Run the five-part checklist before declaring the feature done.

The discipline that makes it work: the const + select() defaults. Most Flutter performance pain shows up as "we'll add const later" / "we'll add `select()` later" — by the time later arrives, the rebuild graph has already metastasized. The skill makes them the first move, not the cleanup pass.

## Receipts

_TODO — to be filled in from a real session. Once the skill has been pointed at a real Flutter project (new or existing), this section will capture: which Riverpod-vs-Bloc pick the skill made for a feature, whether the const + Key + select() discipline actually held in DevTools (should see flat rebuild counts on unrelated widgets when state changes), and whether the GoRouter auth-guard redirect handled deep links cleanly — most common failure mode is a deep-linked URL bypassing the redirect because the guard ran before the auth state hydrated._

## Source and attribution

From [MiniMax-AI's skills repository](https://github.com/MiniMax-AI/skills/tree/main/skills/flutter-dev), an MIT-licensed skill collection. The skill credits the `flutter-expert` skill by Jeff Smolinski as a source framework, alongside the official Flutter, Riverpod, and Bloc documentation.

License: MIT.

The wedge over a generic "Flutter dev" agent: const constructors and `select()`-based granular rebuilds are the default move, not a retrofit. The DevTools-led performance loop (profile → identify → fix → verify) is the same shape as the perf-discipline pattern in other engineering skills, applied to Flutter's render-tree specifics — `RepaintBoundary`, `compute()`, and 16 ms frame budgets.