Flutter SDK Skill

Quick Reference

Flutter is Google's UI toolkit for building natively compiled applications for mobile (iOS, Android), web, and desktop from a single Dart codebase.

Table of Contents

1. Critical: Avoiding Interactive Mode
2. Prerequisites
3. CLI Decision Tree
4. Project Structure
5. State Management
6. Widget Patterns
7. Navigation (GoRouter)
8. Platform-Specific Code
9. Web-Specific Considerations
10. Testing
11. Error Handling
12. CI/CD Integration
13. Auto-Detection Triggers
14. Agent Integration
15. Sources

Critical: Avoiding Interactive Mode

Flutter CLI can enter interactive mode which will hang Claude Code. Always use flags to bypass prompts:

flutter create

flutter create my_app --org com.example

flutter run

flutter run -d <device_id>

flutter build

flutter build apk --release

flutter emulators --launch

flutter emulators --launch <emulator_id>

Always include:

• -d <device_id>

  for device selection (use

  flutter devices

  to list)
• Explicit build targets (

  apk

  ,

  appbundle

  ,

  ios

  ,

  web

  )

• --no-pub

  when pub get is not needed

• --suppress-analytics

  in CI/CD environments

Never use in Claude Code:

• Commands that open GUI (Android Studio, Xcode)
• Interactive device selection prompts
• Commands without explicit targets

Prerequisites

flutter --version          # Expected: Flutter 3.x.x
flutter doctor             # Check all requirements
flutter devices            # List available devices
flutter emulators          # List available emulators

CLI Decision Tree

Project Setup

├── Create new project ────────────────► flutter create <name> --org <org>
├── Get dependencies ──────────────────► flutter pub get
├── Upgrade dependencies ──────────────► flutter pub upgrade
├── Clean build artifacts ─────────────► flutter clean
└── Check project health ──────────────► flutter doctor

Development

├── Run on device ─────────────────────► flutter run -d <device_id>
├── Run in release mode ───────────────► flutter run --release -d <device_id>
├── Attach to running app ─────────────► flutter attach -d <device_id>
└── View logs ─────────────────────────► flutter logs -d <device_id>

Building

├── Build Android APK ─────────────────► flutter build apk --release
├── Build Android App Bundle ──────────► flutter build appbundle --release
├── Build iOS ─────────────────────────► flutter build ios --release
├── Build iOS (no codesign) ───────────► flutter build ios --release --no-codesign
└── Build Web ─────────────────────────► flutter build web --release

Testing

├── Run all tests ─────────────────────► flutter test
├── Run specific test file ────────────► flutter test test/widget_test.dart
├── Run with coverage ─────────────────► flutter test --coverage
└── Run integration tests ─────────────► flutter test integration_test/

Code Quality

├── Analyze code ──────────────────────► flutter analyze
├── Format code ───────────────────────► dart format .
└── Fix lint issues ───────────────────► dart fix --apply

See REFERENCE.md for complete CLI options, flavors, and advanced build configurations.

Project Structure

my_app/
├── lib/
│   ├── main.dart                 # Entry point
│   ├── app.dart                  # App widget
│   ├── features/                 # Feature modules
│   │   └── auth/
│   │       ├── data/             # Repositories, data sources
│   │       ├── domain/           # Entities, use cases
│   │       └── presentation/     # Widgets, providers
│   ├── core/                     # Shared utilities
│   └── l10n/                     # Localization
├── test/                         # Unit and widget tests
├── integration_test/             # Integration tests
├── android/                      # Android platform code
├── ios/                          # iOS platform code
├── web/                          # Web platform code
├── pubspec.yaml                  # Dependencies
└── analysis_options.yaml         # Lint rules

See REFERENCE.md for complete pubspec.yaml and analysis_options.yaml configurations.

State Management

Riverpod (Recommended)

// Provider definition
@riverpod
class Counter extends _$Counter {
  @override
  int build() => 0;

  void increment() => state++;
  void decrement() => state--;
}

// Usage in widget
class CounterWidget extends ConsumerWidget {
  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final count = ref.watch(counterProvider);
    return Text('Count: $count');
  }
}

Provider (Simple apps)

class CartNotifier extends ChangeNotifier {
  final List<Item> _items = [];
  List<Item> get items => List.unmodifiable(_items);

  void addItem(Item item) {
    _items.add(item);
    notifyListeners();
  }
}

// Usage
final cart = context.watch<CartNotifier>();

Bloc (Enterprise apps)

// Events and States
sealed class AuthEvent {}
class LoginRequested extends AuthEvent {
  final String email, password;
  LoginRequested(this.email, this.password);
}

sealed class AuthState {}
class AuthLoading extends AuthState {}
class AuthSuccess extends AuthState { final User user; AuthSuccess(this.user); }

// Bloc
class AuthBloc extends Bloc<AuthEvent, AuthState> {
  AuthBloc() : super(AuthInitial()) {
    on<LoginRequested>(_onLoginRequested);
  }
}

See REFERENCE.md for complete Riverpod architecture, Bloc patterns, and provider types.

Widget Patterns

StatelessWidget

class UserCard extends StatelessWidget {
  final User user;
  final VoidCallback? onTap;

  const UserCard({required this.user, this.onTap, super.key});

  @override
  Widget build(BuildContext context) {
    return Card(
      child: ListTile(
        leading: CircleAvatar(backgroundImage: NetworkImage(user.avatarUrl)),
        title: Text(user.name),
        subtitle: Text(user.email),
        onTap: onTap,
      ),
    );
  }
}

StatefulWidget

class SearchField extends StatefulWidget {
  final ValueChanged<String> onChanged;
  const SearchField({required this.onChanged, super.key});

  @override
  State<SearchField> createState() => _SearchFieldState();
}

class _SearchFieldState extends State<SearchField> {
  final _controller = TextEditingController();
  Timer? _debounce;

  @override
  void dispose() {
    _debounce?.cancel();
    _controller.dispose();
    super.dispose();
  }

  void _onSearchChanged(String value) {
    _debounce?.cancel();
    _debounce = Timer(const Duration(milliseconds: 300), () {
      widget.onChanged(value);
    });
  }

  @override
  Widget build(BuildContext context) {
    return TextField(controller: _controller, onChanged: _onSearchChanged);
  }
}

See REFERENCE.md for compound widgets, builder patterns, and hook widgets.

Navigation (GoRouter)

final router = GoRouter(
  initialLocation: '/',
  routes: [
    GoRoute(
      path: '/',
      builder: (context, state) => const HomeScreen(),
      routes: [
        GoRoute(
          path: 'user/:id',
          builder: (context, state) {
            final id = state.pathParameters['id']!;
            return UserScreen(userId: id);
          },
        ),
      ],
    ),
  ],
  errorBuilder: (context, state) => ErrorScreen(error: state.error),
);

// Usage
context.go('/user/123');
context.push('/user/123');
context.pop();

See REFERENCE.md for deep linking, shell routes, and platform-specific configuration.

Platform-Specific Code

Platform Checks

import 'dart:io' show Platform;
import 'package:flutter/foundation.dart' show kIsWeb;

Widget build(BuildContext context) {
  if (kIsWeb) return WebSpecificWidget();
  if (Platform.isIOS) return CupertinoWidget();
  if (Platform.isAndroid) return MaterialWidget();
  return DefaultWidget();
}

Platform Channels (Native Integration)

class BatteryLevel {
  static const platform = MethodChannel('com.example.app/battery');

  Future<int> getBatteryLevel() async {
    try {
      return await platform.invokeMethod('getBatteryLevel');
    } on PlatformException catch (e) {
      throw Exception('Failed: ${e.message}');
    }
  }
}

See REFERENCE.md for iOS/Android native code, conditional imports, and event channels.

Web-Specific Considerations

Build Renderers

flutter build web --web-renderer canvaskit  # Better fidelity, larger
flutter build web --web-renderer html       # Smaller size
flutter build web --web-renderer auto       # Auto-detect

Best for: Internal tools, dashboards, PWAs, authenticated apps Note: Flutter web renders to canvas - limited SEO by default

Testing

Widget Tests

void main() {
  testWidgets('Counter increments', (tester) async {
    await tester.pumpWidget(const MyApp());
    expect(find.text('0'), findsOneWidget);

    await tester.tap(find.byIcon(Icons.add));
    await tester.pump();

    expect(find.text('1'), findsOneWidget);
  });
}

Golden Tests

testWidgets('Button matches golden', (tester) async {
  await tester.pumpWidget(MaterialApp(home: MyButton(label: 'Submit')));
  await expectLater(find.byType(MyButton), matchesGoldenFile('goldens/my_button.png'));
});

// Update: flutter test --update-goldens

See REFERENCE.md for integration tests, provider testing, and complete test patterns.

Error Handling

No connected devices

flutter devices

Gradle build failed

flutter doctor

CocoaPods not installed

sudo gem install cocoapods

pub get failed

pubspec.yaml

flutter clean

Debug Commands

flutter run -v                    # Verbose output
flutter doctor -v                 # Check for issues
flutter clean && flutter pub get  # Clean rebuild

See REFERENCE.md for complete troubleshooting guide and CI/CD issues.

CI/CD Integration

- uses: subosito/flutter-action@v2
  with:
    flutter-version: "3.24.0"
    channel: stable
    cache: true

- run: flutter pub get
- run: flutter analyze
- run: flutter test --coverage
- run: flutter build apk --release

See REFERENCE.md for complete GitHub Actions workflows and multi-platform builds.

Auto-Detection Triggers

This skill auto-loads when Flutter context is detected:

File-based triggers:

• pubspec.yaml

  with

  flutter

  dependency

• lib/main.dart

  present

• .dart

  files in project

• android/

  and

  ios/

  directories

Context-based triggers:

• User mentions "Flutter"
• User runs flutter CLI commands
• Widget development discussions

Agent Integration

mobile-developer

deep-debugger

code-reviewer

deployment-orchestrator

Handoff to Deep-Debugger:

• Performance profiling needed
• Crash analysis required
• Memory leak investigation
• Platform-specific bugs

Sources

• Flutter CLI Reference
• Flutter Documentation
• Effective Dart
• Flutter State Management