flutter-expert
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.
- License 许可
- MIT
- 最近更新
- 2026-11-08
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- flutter-expert
- license
- MIT
- metadata
- { "role": "specialist", "scope": "implementation", "author": "https://github.com/Jeffallan", "domain": "frontend", "version": "1.1.0", "triggers": "Flutter, Dart, widget, Riverpod, Bloc, GoRouter, cross-platform", "output-format": "code", "related-skills": "react-native-expert, test-master, fullstack-guardian" }
- description
- 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.
02 资源文件 6
- 参考文档references/bloc-state.md4.7 KB
- 参考文档references/gorouter-navigation.md2.6 KB
- 参考文档references/performance.md2.0 KB
- 参考文档references/project-structure.md2.7 KB
- 参考文档references/riverpod-state.md3.0 KB
- 参考文档references/widget-patterns.md2.5 KB
03 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
- Setup — Scaffold project, add dependencies (
flutter pub get), configure routing - State — Define Riverpod providers or Bloc/Cubit classes; verify with
flutter analyze- If
flutter analyzereports issues: fix all lints and warnings before proceeding; re-run until clean
- If
- Widgets — Build reusable, const-optimized components; run
flutter testafter each feature- If tests fail: inspect widget tree with Flutter DevTools, fix failing assertions, re-run
flutter test
- If tests fail: inspect widget tree with Flutter DevTools, fix failing assertions, re-run
- 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
- 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, applyconstor move state closer to consumers
- If jank persists: check rebuild counts in the Performance overlay, isolate expensive
Reference Guide
Load detailed guidance based on context:
| Topic | Reference | Load When |
|---|---|---|
| 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 |
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
constconstructors wherever possible - Implement proper keys for lists
- Use
Consumer/ConsumerWidgetfor state (notStatefulWidget) - 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
setStatefor app-wide state - Skip
conston static widgets - Ignore platform-specific behavior
- Block UI thread with heavy computation (use
compute())
Troubleshooting Common Failures
| 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 |
Output Templates
When implementing Flutter features, provide:
- Widget code with proper
constusage - Provider/Bloc definitions
- Route configuration if needed
- Test file structure
04 同仓库更多 Skills
vss-summarize-video
Use to summarize a recorded video via the LVS summarization microservice (HITL-gated) with a VLM fallback. Not for report generation or live RTSP captioning.
vss-setup-video-analytics-api
Use to deploy the vss-video-analytics-api REST service standalone (config-source, data-log bind, Elasticsearch, optional Kafka). Not for full warehouse deploy.
vss-setup-behavior-analytics
Use to deploy the vss-behavior-analytics service standalone (entrypoint, config-source, optional calibration). Not for the full warehouse deploy.
vss-search-archive
Use this skill to run top-level VSS fusion search on archived video, or to ingest video files / RTSP streams for search. Do NOT use for ad-hoc visual Q&A (use vss-ask-video), live captioning (use vss-deploy-dense-captioning), or video summarization and reports (use vss-summarize-video).
vss-query-analytics
Use this skill when reading video-analytics metrics, incidents, alerts, and sensor data via the VA-MCP server (port 9901). Not for live VLM or incident-range narrative reports.
vss-manage-video-io-storage
Use to call the VIOS REST API (sensor list, timelines, clip extraction, snapshots, add/delete sensors and streams). Not for VLM inference or search.