Jeffallan/claude-skills/flutter-expert

// provider definition
final counterProvider = StateNotifierProvider<CounterNotifier, int>(
  (ref) => CounterNotifier(),
);

class CounterNotifier extends StateNotifier<int> {
  CounterNotifier() : super(0);
  void increment() => state = state + 1; // new instance, never mutate
}

// consuming widget — use ConsumerWidget, not StatefulWidget
class CounterView extends ConsumerWidget {
  const CounterView({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Text('$count');
  }
}

// ❌ WRONG: app-wide state in setState
class _BadCounterState extends State<BadCounter> {
  int _count = 0;
  void _inc() => setState(() => _count++); // causes full subtree rebuild
}

// ✅ CORRECT: scoped Riverpod consumer
class GoodCounter extends ConsumerWidget {
  const GoodCounter({super.key});
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return IconButton(
      onPressed: () => ref.read(counterProvider.notifier).increment(),
      icon: const Icon(Icons.add), // const on static widgets
    );
  }
}

Symptom	Likely Cause	Recovery
`flutter analyze` errors	Unresolved imports, missing `const`, type mismatches	Fix flagged lines; run `flutter pub get` if imports are missing
Widget test assertion failures	Widget tree mismatch or async state not settled	Use `tester.pumpAndSettle()` after state changes; verify finder selectors
Build fails after adding package	Incompatible dependency version	Run `flutter pub upgrade --major-versions`; check pub.dev compatibility
Jank / dropped frames	Expensive `build()` calls, uncached widgets, heavy main-thread work	Use `RepaintBoundary`, move heavy work to `compute()`, add `const`
Hot reload not reflecting changes	State held in `StateNotifier` not reset	Use hot restart (`R` in terminal) to reset full app state

Riverpod	`references/riverpod-state.md`	State management, providers, notifiers
Bloc	`references/bloc-state.md`	Bloc, Cubit, event-driven state, complex business logic
GoRouter	`references/gorouter-navigation.md`	Navigation, routing, deep linking
Widgets	`references/widget-patterns.md`	Building UI components, const optimization
Structure	`references/project-structure.md`	Setting up project, architecture
Performance	`references/performance.md`	Optimization, profiling, jank fixes

flutter-expert

Summary

SKILL.md

Flutter Expert

When to Use This Skill

Core Workflow

Reference Guide

Code Examples

Riverpod Provider + ConsumerWidget (correct pattern)

Before / After — State Management

Constraints

MUST DO

MUST NOT DO

Troubleshooting Common Failures

Output Templates

Related skills