agentleFS
Sign inStart free
codeApe-7codeApe-7/ai-agent-workflowGroup/skills/frontend/flutter-expert/SKILL.md

flutter-expert

Skill18 starsChanged 5 months agoMITView on GitHub

Use when building cross-platform applications with Flutter 3+ and Dart. Invoke for widget development, Riverpod/Bloc state management, GoRouter navigation, platform-specific implementations, performance optimization.

We split this skill into the rules it gives an agent

10 rules. 2 are common, 1 is distinctive, and 7 are very specific to this project.

  • 2

    Common

    Most of the 15 edited versions we read keep these.

  • 1

    Distinctive

    This author's own choices. Worth a look.

  • 7

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    If flutter analyze reports issues: fix all lints and warnings before proceeding.

    line 33
  2. Very specific:

    If tests fail: inspect widget tree with Flutter DevTools, fix failing assertions, re-run flutter test

    line 35
  3. Distinctive:

    If coverage drops or tests fail: identify untested branches, add targeted tests, re-run before merging

    line 37
  4. Very specific:

    If jank persists: check rebuild counts in the Performance overlay, isolate expensive build() calls, apply const or move state closer to …

    line 39
  5. Very specific:

    Use const constructors wherever possible

    line 107
  6. Very specific:

    Use Consumer/ConsumerWidget for state (not StatefulWidget)

    line 109
  7. Common:

    Follow Material/Cupertino design guidelines

    line 110
  8. Very specific:

    Test widgets with flutter_test

    line 112
  9. Very specific:

    Use setState for app-wide state

    line 117
  10. Common:

    When implementing Flutter features, provide:

    line 134

“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Flutter Expert

Senior mobile engineer building high-performance cross-platform applications with Flutter 3 and Dart.

When to Use This Skill

  • Building cross-platform Flutter applications
  • Implementing state management (Riverpod, Bloc)
  • Setting up navigation with GoRouter
  • Creating custom widgets and animations
  • Optimizing Flutter performance
  • Platform-specific implementations

Core Workflow

  1. Setup — Scaffold project, add dependencies (flutter pub get), configure routing
  2. State — Define Riverpod providers or Bloc/Cubit classes; verify with flutter analyze
    • If flutter analyze reports issues: fix all lints and warnings before proceeding; re-run until clean
  3. Widgets — Build reusable, const-optimized components; run flutter test after each feature
    • If tests fail: inspect widget tree with Flutter DevTools, fix failing assertions, re-run flutter test
  4. Test — Write widget and integration tests; confirm with flutter test --coverage
    • If coverage drops or tests fail: identify untested branches, add targeted tests, re-run before merging
  5. Optimize — Profile with Flutter DevTools (flutter run --profile), eliminate jank, reduce rebuilds
    • If jank persists: check rebuild counts in the Performance overlay, isolate expensive build() calls, apply const or move state closer to consumers

Reference Guide

Load detailed guidance based on context:

TopicReferenceLoad When
Riverpodreferences/riverpod-state.mdState management, providers, notifiers
Blocreferences/bloc-state.mdBloc, Cubit, event-driven state, complex business logic
GoRouterreferences/gorouter-navigation.mdNavigation, routing, deep linking
Widgetsreferences/widget-patterns.mdBuilding UI components, const optimization
Structurereferences/project-structure.mdSetting up project, architecture
Performancereferences/performance.mdOptimization, profiling, jank fixes

Code Examples

Riverpod Provider + ConsumerWidget (correct pattern)

// 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');
  }
}

Before / After — State Management

// ❌ 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
    );
  }
}

Constraints

MUST DO

  • Use const constructors wherever possible
  • Implement proper keys for lists
  • Use Consumer/ConsumerWidget for state (not StatefulWidget)
  • Follow Material/Cupertino design guidelines
  • Profile with DevTools, fix jank
  • Test widgets with flutter_test

MUST NOT DO

  • Build widgets inside build() method
  • Mutate state directly (always create new instances)
  • Use setState for app-wide state
  • Skip const on static widgets
  • Ignore platform-specific behavior
  • Block UI thread with heavy computation (use compute())

Troubleshooting Common Failures

SymptomLikely CauseRecovery
flutter analyze errorsUnresolved imports, missing const, type mismatchesFix flagged lines; run flutter pub get if imports are missing
Widget test assertion failuresWidget tree mismatch or async state not settledUse tester.pumpAndSettle() after state changes; verify finder selectors
Build fails after adding packageIncompatible dependency versionRun flutter pub upgrade --major-versions; check pub.dev compatibility
Jank / dropped framesExpensive build() calls, uncached widgets, heavy main-thread workUse RepaintBoundary, move heavy work to compute(), add const
Hot reload not reflecting changesState held in StateNotifier not resetUse hot restart (R in terminal) to reset full app state

Output Templates

When implementing Flutter features, provide:

  1. Widget code with proper const usage
  2. Provider/Bloc definitions
  3. Route configuration if needed
  4. Test file structure

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free